6.7 KiB
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
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
Project Setup
-
Clone the repository:
git clone https://github.com/jetkvm/kvm.git cd kvm
-
Check your tools:
go version && node --version
-
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.
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
# Edit Go files (config.go, web.go, 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
Key files for beginners:
web.go
- Add new API endpoints hereconfig.go
- Add new settings hereui/src/routes/
- Add new pages hereui/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 or backend logic changes
# 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
"Can't connect to device"
# Check network
ping <IP>
# Check SSH
ssh root@<IP> echo "Connection OK"
"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
- 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
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.