docs: rewrite DEVELOPMENT.md for clearer setup and usage

Revise the JetKVM development guide to improve clarity and usability.
Simplify the introduction and reorganize prerequisites and setup steps
to help new developers get started quickly. Add explicit instructions for
cloning, tool verification, deployment, and testing. Streamline common
tasks sections with clear commands for UI and backend development,
testing, and log viewing. Update project layout overview for easier
navigation. These changes reduce onboarding friction and enhance the
developer experience.
This commit is contained in:
Silke pilon 2025-07-15 21:59:49 +02:00 committed by GitButler
parent b3cdaaa8dc
commit a4c82e2f05
1 changed files with 264 additions and 395 deletions

View File

@ -13,154 +13,295 @@
# JetKVM Development Guide
This guide provides comprehensive information for developing, testing, and debugging JetKVM. Whether you're adding new features, fixing bugs, or contributing to the project, this document will help you get started.
Welcome to JetKVM development! This guide will help you get started quickly, whether you're fixing bugs, adding features, or just exploring the codebase.
## Prerequisites
## Get Started
Before you begin development, ensure you have the following tools installed:
## Get Started
- **Go 1.24.4+** - Backend development
- **Node.js 22.15.0** - Frontend development
- **npm** - Package management (comes with Node.js)
- **Make** - Build automation
- **Git** - Version control
- **SSH access** - For device deployment and debugging
### 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
### Verify Installation
### Project Setup
```bash
go version # Should show Go 1.24.4+
node --version # Should show v22.15.0
npm --version # Should show npm version
make --version # Should show Make version
```
1. **Clone the repository:**
```bash
git clone https://github.com/jetkvm/kvm.git
cd kvm
```
## Project Structure
2. **Check your tools:**
```bash
go version && node --version
```
```
/kvm/
├── main.go # Main application entry point
├── config.go # Configuration management
├── web.go # Web server and API endpoints
├── Makefile # Build automation
├── dev_deploy.sh # Development deployment script
├── go.mod # Go module dependencies
├── ui/ # Frontend React application
│ ├── src/
│ │ ├── routes/ # Page components
│ │ ├── components/ # Reusable UI components
│ │ ├── hooks/ # React hooks
│ │ └── api.ts # API client
│ ├── dev_device.sh # Frontend dev server script
│ └── package.json # Frontend dependencies
├── internal/ # Internal Go packages
│ ├── logging/ # Logging utilities
│ ├── network/ # Network configuration
│ └── usbgadget/ # USB gadget management
├── resource/ # Static resources
└── bin/ # Built binaries
```
3. **Find your JetKVM IP address** (check your router or device screen)
## Development Approaches
4. **Deploy and test:**
```bash
./dev_deploy.sh -r 192.168.1.100 # Replace with your device IP
```
### 1. Full Device Development (Recommended)
5. **Open in browser:** `http://192.168.1.100`
This approach requires an actual JetKVM device and provides the most complete development environment.
That's it! You're now running your own development version of JetKVM.
#### Quick Start
---
```bash
# Deploy to your JetKVM device
./dev_deploy.sh -r <YOUR_JETKVM_IP>
## Common Tasks
# Example:
./dev_deploy.sh -r 192.168.1.100
```
#### Development Workflow
```bash
# 1. Build frontend and backend, then deploy
./dev_deploy.sh -r 192.168.1.100
# 2. Skip frontend build for faster iteration (backend changes only)
./dev_deploy.sh -r 192.168.1.100 --skip-ui-build
# 3. Run Go tests on device
./dev_deploy.sh -r 192.168.1.100 --run-go-tests
# 4. Only run tests without deployment
./dev_deploy.sh -r 192.168.1.100 --run-go-tests-only
# 5. Use custom username (default: root)
./dev_deploy.sh -r 192.168.1.100 -u admin
```
#### Manual Build Commands
```bash
# Build frontend for device
make frontend
# Build Go binary for ARM Linux
make build_dev
# Build development version with tests
make build_dev_test
# Build release version
make build_release
```
### 2. Frontend-Only Development
For UI development without requiring a physical device.
#### Setup
### Modify the UI
```bash
cd ui
npm install
./dev_device.sh 192.168.1.100 # Replace with your device IP
```
#### Development Server
Now edit files in `ui/src/` and see changes live in your browser!
### Modify the backend
```bash
# Start dev server pointing to a JetKVM device
./dev_device.sh <JETKVM_IP>
# Example:
./dev_device.sh 192.168.1.100
# Alternative npm scripts:
npm run dev <JETKVM_IP> # Standard development
npm run dev:ssl <JETKVM_IP> # With SSL enabled
npm run dev:cloud # Cloud development mode
# Edit Go files (config.go, web.go, etc.)
./dev_deploy.sh -r 192.168.1.100 --skip-ui-build
```
#### Build Commands
### Run tests
```bash
# Build for device deployment
npm run build:device
# Build for production cloud
npm run build:prod
# Build for staging environment
npm run build:staging
# Lint code
npm run lint
# Fix linting issues automatically
npm run lint:fix
./dev_deploy.sh -r 192.168.1.100 --run-go-tests
```
## Development Environment Configuration
### View logs
```bash
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 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*
```bash
# Deploy everything to your JetKVM device
./dev_deploy.sh -r <YOUR_DEVICE_IP>
```
### Frontend Only
*Best for: UI changes without device*
```bash
cd ui
npm install
./dev_device.sh <YOUR_DEVICE_IP>
```
### Quick Backend Changes
*Best for: API or backend logic changes*
```bash
# Skip frontend build for faster deployment
./dev_deploy.sh -r <YOUR_DEVICE_IP> --skip-ui-build
```
---
## Debugging Made Easy
### Check if everything is working
```bash
# 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
```bash
ssh root@192.168.1.100
tail -f /var/log/jetkvm.log
```
### Reset everything (if stuck)
```bash
ssh root@192.168.1.100
rm /userdata/kvm_config.json
systemctl restart jetkvm
```
---
## Testing Your Changes
### Manual Testing
1. Deploy your changes: `./dev_deploy.sh -r <IP>`
2. Open browser: `http://<IP>`
3. Test your feature
4. Check logs: `ssh root@<IP> tail -f /var/log/jetkvm.log`
### Automated Testing
```bash
# Run all tests
./dev_deploy.sh -r <IP> --run-go-tests
# Frontend linting
cd ui && npm run lint
```
### API Testing
```bash
# 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"
```bash
# 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"
```bash
# Check network
ping <IP>
# Check SSH
ssh root@<IP> echo "Connection OK"
```
### "Frontend not updating"
```bash
# Clear cache and rebuild
cd ui
npm cache clean --force
rm -rf node_modules
npm install
```
---
## Next Steps
### Adding a New Feature
1. **Backend:** Add API endpoint in `web.go`
2. **Config:** Add settings in `config.go`
3. **Frontend:** Add UI in `ui/src/routes/`
4. **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
```bash
# Enable debug logging
export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc"
# Frontend development
export JETKVM_PROXY_URL="ws://<IP>"
```
---
## Need Help?
1. **Check logs first:** `ssh root@<IP> tail -f /var/log/jetkvm.log`
2. **Search issues:** [GitHub Issues](https://github.com/jetkvm/kvm/issues)
3. **Ask on Discord:** [JetKVM Discord](https://jetkvm.com/discord)
4. **Read docs:** [JetKVM Documentation](https://jetkvm.com/docs)
---
## Contributing
### Ready to contribute?
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
### Before submitting:
- [ ] Code works on device
- [ ] Tests pass
- [ ] Code follows style guidelines
- [ ] Documentation updated (if needed)
---
## Advanced Topics
### Performance Profiling
```bash
# 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
```bash
# Enable trace logging (useful for debugging)
export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc"
@ -172,174 +313,6 @@ export JETKVM_PROXY_URL="ws://<JETKVM_IP>"
export USE_SSL=true
```
### Go Build Configuration
The project uses cross-compilation for ARM Linux. Build settings are configured in the Makefile:
```makefile
GO_CMD := GOOS=linux GOARCH=arm GOARM=7 go
```
## Testing
### Backend Testing
```bash
# Run Go tests locally
go test ./...
# Build and run tests on device
make build_dev_test
# Deploy with tests to device
./dev_deploy.sh -r <IP> --run-go-tests
# Run only tests (no deployment)
./dev_deploy.sh -r <IP> --run-go-tests-only
```
### Frontend Testing
```bash
cd ui
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Start development server for manual testing
npm run dev <JETKVM_IP>
```
### Integration Testing
1. **Deploy your changes:**
```bash
./dev_deploy.sh -r <JETKVM_IP>
```
2. **Access the web interface:**
- Navigate to `http://<JETKVM_IP>` in your browser
- Test your changes in the UI
3. **API testing with curl:**
```bash
# Test authentication endpoints
curl -X POST http://<IP>/auth/password-local \
-H "Content-Type: application/json" \
-d '{"password": "test123"}'
# Test device status
curl http://<IP>/device/status
```
## Debugging
### Application Logs
```bash
# SSH into device
ssh root@<IP>
# View real-time application logs
tail -f /var/log/jetkvm.log
# View systemd logs
journalctl -u jetkvm -f
# View specific log levels
journalctl -u jetkvm -p err
```
### Process Management
```bash
# Check running processes
ps aux | grep jetkvm
# Kill development instance
killall jetkvm_app_debug
# Kill production instance
killall jetkvm_app
# Restart service
systemctl restart jetkvm
```
### Configuration Debugging
```bash
# View current configuration
ssh root@<IP>
cat /userdata/kvm_config.json
# Reset configuration (be careful!)
rm /userdata/kvm_config.json
systemctl restart jetkvm
```
### Network Debugging
```bash
# Check network interfaces
ip addr show
# Test connectivity
ping <TARGET_IP>
# Check open ports
netstat -tulpn | grep jetkvm
```
## Common Development Tasks
### Quick Testing Cycle
```bash
# 1. Make your code changes
# 2. Deploy to device (skip frontend if only backend changes)
./dev_deploy.sh -r <IP> --skip-ui-build
# 3. Test in browser at http://<IP>
# 4. Check logs if needed
ssh root@<IP>
tail -f /var/log/jetkvm.log
```
### Adding New Features
1. **Backend changes:**
- Modify `config.go` for new configuration options
- Add API endpoints in `web.go`
- Update request/response structures
2. **Frontend changes:**
- Add new routes in `ui/src/routes/`
- Create reusable components in `ui/src/components/`
- Update API client in `ui/src/api.ts`
3. **Testing:**
- Write Go tests for backend functionality
- Test UI changes with `npm run dev`
- Deploy and test integration
### Code Style Guidelines
#### Go Code
- Follow standard Go conventions
- Use meaningful variable names
- Add comments for exported functions
- Handle errors appropriately
#### TypeScript/React Code
- Use TypeScript for type safety
- Follow React hooks patterns
- Use consistent naming conventions
- Keep components focused and reusable
### Configuration Management
The application uses a JSON configuration file stored at `/userdata/kvm_config.json`.
@ -347,6 +320,7 @@ The application uses a JSON configuration file stored at `/userdata/kvm_config.j
#### Adding New Configuration Options
1. **Update the Config struct in `config.go`:**
```go
type Config struct {
// ... existing fields
@ -355,6 +329,7 @@ The application uses a JSON configuration file stored at `/userdata/kvm_config.j
```
2. **Update the default configuration:**
```go
var defaultConfig = &Config{
// ... existing defaults
@ -364,115 +339,9 @@ The application uses a JSON configuration file stored at `/userdata/kvm_config.j
3. **Add migration logic if needed for existing installations**
## Troubleshooting
### Common Issues
---
#### Build Failures
```bash
# Clear Go module cache
go clean -modcache
# Update dependencies
go mod tidy
# Rebuild from scratch
make clean && make build_dev
```
#### Frontend Issues
```bash
# Clear npm cache
npm cache clean --force
# Remove node_modules and reinstall
rm -rf node_modules
npm install
# Check for TypeScript errors
npm run lint
```
#### Device Connection Issues
```bash
# Check SSH connectivity
ssh root@<IP> echo "Connection OK"
# Verify device is accessible
ping <IP>
# Check if device is running JetKVM
ssh root@<IP> ps aux | grep jetkvm
```
#### Permission Issues
```bash
# Fix binary permissions on device
ssh root@<IP> chmod +x /userdata/jetkvm/bin/jetkvm_app_debug
# Check file ownership
ssh root@<IP> ls -la /userdata/jetkvm/bin/
```
### Getting Help
1. **Check the logs first** - Most issues can be diagnosed from application logs
2. **Search existing issues** - Check [GitHub Issues](https://github.com/jetkvm/kvm/issues)
3. **Ask on Discord** - Join our [Discord Server](https://jetkvm.com/discord)
4. **Read the documentation** - Visit [JetKVM Docs](https://jetkvm.com/docs)
## Contributing
### Before Submitting a Pull Request
1. **Test your changes thoroughly**
2. **Run linting and fix any issues**
3. **Write tests for new functionality**
4. **Update documentation if needed**
5. **Follow the existing code style**
### Pull Request Process
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request with a clear description
### Code Review Guidelines
- Be respectful and constructive
- Focus on the code, not the person
- Provide specific, actionable feedback
- Test the changes locally when possible
## Advanced Development Topics
### Cross-Compilation
The project builds for ARM Linux by default. To build for other architectures:
```bash
# Build for x86_64 Linux
GOOS=linux GOARCH=amd64 go build -o bin/jetkvm_app_x64 cmd/main.go
# Build for current platform
go build -o bin/jetkvm_app_native cmd/main.go
```
### Performance Profiling
```bash
# Enable profiling in development
go build -o bin/jetkvm_app -ldflags="-X main.enableProfiling=true" cmd/main.go
# Access profiling endpoints
curl http://<IP>:6060/debug/pprof/
```
**Happy coding!**
For more information, visit the [JetKVM Documentation](https://jetkvm.com/docs) or join our [Discord Server](https://jetkvm.com/discord).