9.8 KiB

Raw Blame History

Development Guide

JetKVM Development Guide

Welcome to JetKVM development! This guide will help you get started quickly, whether you're fixing bugs, adding features, or just exploring the codebase.

Get Started

Prerequisites

A JetKVM device (for full development)
Go 1.24.4+ and Node.js 22.15.0
Git for version control
SSH access to your JetKVM device
Audio build dependencies:
- New in this release: The audio pipeline is now fully in-process using CGO, ALSA, and Opus. You must run the provided scripts in tools/ to set up the cross-compiler and build static ALSA/Opus libraries for ARM. See below.

Development Environment

Recommended: Development is best done on Linux or macOS.

Apple Silicon (M1/M2/M3) Mac Users

If you are developing on an Apple Silicon Mac, you should use a devcontainer to ensure compatibility with the JetKVM build environment (which targets linux/amd64 and ARM). There are two main options:

VS Code Dev Containers: Open the project in VS Code and use the built-in Dev Containers support. The configuration is in .devcontainer/devcontainer.json.
Devpod: Devpod is a fast, open-source tool for running devcontainers anywhere. If you use Devpod, go to Settings → Experimental → Additional Environmental Variables and add:
- DOCKER_DEFAULT_PLATFORM=linux/amd64 This ensures all builds run in the correct architecture.
devcontainer CLI: You can also use the devcontainer CLI to launch the devcontainer from the terminal.

This approach ensures compatibility with all shell scripts, build tools, and cross-compilation steps used in the project.

If you're using Windows, we strongly recommend using WSL (Windows Subsystem for Linux) for the best development experience:

This ensures compatibility with shell scripts and build tools used in the project.

Project Setup

Clone the repository:

git clone https://github.com/jetkvm/kvm.git
cd kvm

Check your tools:
```
go version && node --version
```

Set up the cross-compiler and audio dependencies:

make dev_env
# This will run tools/setup_rv1106_toolchain.sh and tools/build_audio_deps.sh
# It will clone the cross-compiler and build ALSA/Opus static libs in $HOME/.jetkvm
#
# **Note:** This is required for the new in-process audio pipeline. If you skip this step, audio will not work.

Find your JetKVM IP address (check your router or device screen)

Deploy and test:

./dev_deploy.sh -r 192.168.1.100  # Replace with your device IP

Open in browser: http://192.168.1.100

That's it! You're now running your own development version of JetKVM, with in-process audio streaming for the first time.

Common Tasks

Modify the UI

cd ui
npm install
./dev_device.sh 192.168.1.100  # Replace with your device IP

Now edit files in ui/src/ and see changes live in your browser!

Modify the backend (including audio)

# Edit Go files (config.go, web.go, internal/audio, etc.)
./dev_deploy.sh -r 192.168.1.100 --skip-ui-build

Run tests

./dev_deploy.sh -r 192.168.1.100 --run-go-tests

View logs

ssh root@192.168.1.100
tail -f /var/log/jetkvm.log

Project Layout

/kvm/
├── main.go              # App entry point
├── config.go            # Settings & configuration
├── web.go               # API endpoints
├── ui/                  # React frontend
│   ├── src/routes/      # Pages (login, settings, etc.)
│   └── src/components/  # UI components
├── internal/            # Internal Go packages
│   └── audio/           # In-process audio pipeline (CGO, ALSA, Opus) [NEW]
├── tools/               # Toolchain and audio dependency setup scripts
└── Makefile             # Build and dev automation (see audio targets)

Key files for beginners:

internal/audio/ - [NEW] In-process audio pipeline (CGO, ALSA, Opus)
web.go - Add new API endpoints here
config.go - Add new settings here
ui/src/routes/ - Add new pages here
ui/src/components/ - Add new UI components here

Development Modes

Full Development (Recommended)

Best for: Complete feature development

# Deploy everything to your JetKVM device
./dev_deploy.sh -r <YOUR_DEVICE_IP>

Frontend Only

Best for: UI changes without device

cd ui
npm install
./dev_device.sh <YOUR_DEVICE_IP>

Quick Backend Changes

Best for: API, backend, or audio logic changes (including audio pipeline)

# Skip frontend build for faster deployment
./dev_deploy.sh -r <YOUR_DEVICE_IP> --skip-ui-build

Debugging Made Easy

Check if everything is working

# Test connection to device
ping 192.168.1.100

# Check if JetKVM is running
ssh root@192.168.1.100 ps aux | grep jetkvm

View live logs

ssh root@192.168.1.100
tail -f /var/log/jetkvm.log

Reset everything (if stuck)

ssh root@192.168.1.100
rm /userdata/kvm_config.json
systemctl restart jetkvm

Testing Your Changes

Manual Testing

Deploy your changes: ./dev_deploy.sh -r <IP>
Open browser: http://<IP>
Test your feature
Check logs: ssh root@<IP> tail -f /var/log/jetkvm.log

Automated Testing

# Run all tests
./dev_deploy.sh -r <IP> --run-go-tests

# Frontend linting
cd ui && npm run lint

API Testing

# Test login endpoint
curl -X POST http://<IP>/auth/password-local \
  -H "Content-Type: application/json" \
  -d '{"password": "test123"}'

Common Issues & Solutions

"Build failed" or "Permission denied"

# Fix permissions
ssh root@<IP> chmod +x /userdata/jetkvm/bin/jetkvm_app_debug

# Clean and rebuild
go clean -modcache
go mod tidy
make build_dev
# If you see errors about missing ALSA/Opus or toolchain, run:
make dev_env  # Required for new audio support

"Can't connect to device"

# Check network
ping <IP>

# Check SSH
ssh root@<IP> echo "Connection OK"

"Audio not working"

# Make sure you have run:
make dev_env
# If you see errors about ALSA/Opus, check logs and re-run the setup scripts in tools/.

"Frontend not updating"

# Clear cache and rebuild
cd ui
npm cache clean --force
rm -rf node_modules
npm install

Next Steps

Adding a New Feature

Backend: Add API endpoint in web.go or extend audio in internal/audio/
Config: Add settings in config.go
Frontend: Add UI in ui/src/routes/
Test: Deploy and test with ./dev_deploy.sh

Code Style

Go: Follow standard Go conventions
TypeScript: Use TypeScript for type safety
React: Keep components small and reusable
Audio/CGO: Keep C/Go integration minimal, robust, and well-documented. Use zerolog for all logging.

Environment Variables

# Enable debug logging
export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc"

# Frontend development
export JETKVM_PROXY_URL="ws://<IP>"

Need Help?

Check logs first: ssh root@<IP> tail -f /var/log/jetkvm.log
Search issues: GitHub Issues
Ask on Discord: JetKVM Discord
Read docs: JetKVM Documentation

Contributing

Ready to contribute?

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Before submitting:

Code works on device
Tests pass
Code follows style guidelines
Documentation updated (if needed)

Advanced Topics

Performance Profiling

# Enable profiling
go build -o bin/jetkvm_app -ldflags="-X main.enableProfiling=true" cmd/main.go

# Access profiling
curl http://<IP>:6060/debug/pprof/

Advanced Environment Variables

# Enable trace logging (useful for debugging)
export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc"

# For frontend development
export JETKVM_PROXY_URL="ws://<JETKVM_IP>"

# Enable SSL in development
export USE_SSL=true

Configuration Management

The application uses a JSON configuration file stored at /userdata/kvm_config.json.

Adding New Configuration Options

Update the Config struct in config.go:

type Config struct {
    // ... existing fields
    NewFeatureEnabled bool `json:"new_feature_enabled"`
}

Update the default configuration:

var defaultConfig = &Config{
    // ... existing defaults
    NewFeatureEnabled: false,
}

Add migration logic if needed for existing installations

Happy coding!

For more information, visit the JetKVM Documentation or join our Discord Server.

9.8 KiB Raw Blame History