diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 20f28ee..b41ef2b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -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 +## 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 - -# Example: -./dev_device.sh 192.168.1.100 - -# Alternative npm scripts: -npm run dev # Standard development -npm run dev:ssl # 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 +``` + +### Frontend Only + +*Best for: UI changes without device* + +```bash +cd ui +npm install +./dev_device.sh +``` + +### Quick Backend Changes + +*Best for: API or backend logic changes* + +```bash +# Skip frontend build for faster deployment +./dev_deploy.sh -r --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 ` +2. Open browser: `http://` +3. Test your feature +4. Check logs: `ssh root@ tail -f /var/log/jetkvm.log` + +### Automated Testing + +```bash +# Run all tests +./dev_deploy.sh -r --run-go-tests + +# Frontend linting +cd ui && npm run lint +``` + +### API Testing + +```bash +# Test login endpoint +curl -X POST http:///auth/password-local \ + -H "Content-Type: application/json" \ + -d '{"password": "test123"}' +``` + +--- + +## Common Issues & Solutions + +### "Build failed" or "Permission denied" + +```bash +# Fix permissions +ssh root@ 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 + +# Check SSH +ssh root@ 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://" +``` + +--- + +## Need Help? + +1. **Check logs first:** `ssh root@ 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://:6060/debug/pprof/ +``` +### Advanced Environment Variables + ```bash # Enable trace logging (useful for debugging) export LOG_TRACE_SCOPES="jetkvm,cloud,websocket,native,jsonrpc" @@ -172,181 +313,14 @@ export JETKVM_PROXY_URL="ws://" 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 --run-go-tests - -# Run only tests (no deployment) -./dev_deploy.sh -r --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 -``` - -### Integration Testing - -1. **Deploy your changes:** - ```bash - ./dev_deploy.sh -r - ``` - -2. **Access the web interface:** - - Navigate to `http://` in your browser - - Test your changes in the UI - -3. **API testing with curl:** - ```bash - # Test authentication endpoints - curl -X POST http:///auth/password-local \ - -H "Content-Type: application/json" \ - -d '{"password": "test123"}' - - # Test device status - curl http:///device/status - ``` - -## Debugging - -### Application Logs - -```bash -# SSH into device -ssh root@ - -# 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@ -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 - -# 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 --skip-ui-build - -# 3. Test in browser at http:// -# 4. Check logs if needed -ssh root@ -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`. +The application uses a JSON configuration file stored at `/userdata/kvm_config.json`. #### 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@ echo "Connection OK" - -# Verify device is accessible -ping - -# Check if device is running JetKVM -ssh root@ ps aux | grep jetkvm -``` - -#### Permission Issues - -```bash -# Fix binary permissions on device -ssh root@ chmod +x /userdata/jetkvm/bin/jetkvm_app_debug - -# Check file ownership -ssh root@ 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://: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).