Skip to content

Development Guide

Project overview

One-KVM is a lightweight IP-KVM service written in Rust. The frontend uses Vue 3, TypeScript, and Vite. The backend embeds web/dist with rust-embed; set ONE_KVM_FRONTEND_DIR to serve an external frontend directory during development.

Local development and build

From the project root:

1
2
3
4
5
cd web
npm install
npm run build
cd ..
cargo build

Run the frontend development server and backend separately:

1
2
3
4
cd web
npm run dev
# In another terminal, from the project root:
cargo run -- --log-level debug

Run checks with cargo test and cd web && npm run build.

On Windows, install the vcpkg dependencies and run build/windows/build.ps1. The script checks VCPKG_ROOT, VCPKG_INSTALLED_DIR, and the x64-windows-static triplet. Use -Configuration release -Package to create a package, or override -Target, -Triplet, -NoDefaultFeatures, and -Features as needed.

Cross-platform builds

Install cross and make sure Docker is available:

1
2
3
4
5
6
cargo install cross
./build/build-images.sh              # x86_64, arm64, and armv7
./build/build-images.sh x86_64
./build/build-images.sh arm64
./build/build-images.sh armv7
./build/build-images.sh --help

Binaries are written to target/<rust-target>/release/one-kvm. In mainland China, use CHINAMIRRO=1 when a mirror is needed.

DEB and Docker packages

Use ./build/package-deb.sh to create DEB packages. Use ./build/package-docker.sh to package a precompiled binary into a Docker image. Important options include --platform, --registry, --image-name, --tag, --variant minimal|full, --push, --load, and --build.

The full image includes optional gostc and easytier programs. Keep image tags and target platforms consistent when publishing multi-architecture manifests.

Frontend and API notes

The frontend communicates with the backend through REST and WebSocket endpoints. When adding a page or setting, update both language trees where applicable, keep validation consistent with the backend, and add screenshots to the relevant UI guide only when they are referenced by the page.