Merge ced12780a4 into badbc9759d

docs: add comprehensive DEVELOPMENT.md for JetKVM (#692 )
* docs: add comprehensive DEVELOPMENT.md for JetKVM Add a detailed development guide covering setup, project structure, and workflows for both full device and frontend-only development. Include prerequisites, build commands, deployment scripts, environment variables, and testing instructions to streamline onboarding and contributions. This improves developer experience and standardizes development practices across the project. * docs: clean up DEVELOPMENT.md by removing outdated sections Remove the Custom Build Tags and Release Process sections to simplify the documentation and avoid confusion with deprecated build and release instructions. Focus the document on current performance profiling steps. * 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. * docs: remove duplicate "Get Started" header in DEVELOPMENT.md Clean up the DEVELOPMENT.md file by deleting the repeated "Get Started" header * docs: add recommended development environment section Add guidance recommending Linux or macOS for development and suggest using WSL on Windows to ensure compatibility with shell scripts and build tools. This improves the developer experience and reduces setup issues across different operating systems. * docs: add links to prerequisites in DEVELOPMENT.md Update DEVELOPMENT.md to URLs for Go, Node.js, Git, and SSH access prerequisites. This improves clarity and helps developers quickly find installation resources.
2025-07-15 21:43:16 +00:00 · 2025-07-15 23:40:42 +02:00 · 2025-07-11 06:07:30 +00:00
4 changed files with 430 additions and 12 deletions
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@ -0,0 +1,355 @@
+<div align="center">
+    <img alt="JetKVM logo" src="https://jetkvm.com/logo-blue.png" height="28">
+
+### Development Guide
+
+[Discord](https://jetkvm.com/discord) | [Website](https://jetkvm.com) | [Issues](https://github.com/jetkvm/cloud-api/issues) | [Docs](https://jetkvm.com/docs)
+
+[![Twitter](https://img.shields.io/twitter/url/https/twitter.com/jetkvm.svg?style=social&label=Follow%20%40JetKVM)](https://twitter.com/jetkvm)
+
+[![Go Report Card](https://goreportcard.com/badge/github.com/jetkvm/kvm)](https://goreportcard.com/report/github.com/jetkvm/kvm)
+
+</div>
+
+# 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+](https://go.dev/doc/install)** and **[Node.js 22.15.0](https://nodejs.org/en/download/)**
+- **[Git](https://git-scm.com/downloads)** for version control
+- **[SSH access](https://jetkvm.com/docs/advanced-usage/developing#developer-mode)** to your JetKVM device
+
+### Development Environment
+
+**Recommended:** Development is best done on **Linux** or **macOS**. 
+
+If you're using Windows, we strongly recommend using **WSL (Windows Subsystem for Linux)** for the best development experience:
+- [Install WSL on Windows](https://docs.microsoft.com/en-us/windows/wsl/install)
+- [WSL Setup Guide](https://docs.microsoft.com/en-us/windows/wsl/setup/environment)
+
+This ensures compatibility with shell scripts and build tools used in the project.
+
+### Project Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/jetkvm/kvm.git
+   cd kvm
+   ```
+
+2. **Check your tools:**
+   ```bash
+   go version && node --version
+   ```
+
+3. **Find your JetKVM IP address** (check your router or device screen)
+
+4. **Deploy and test:**
+   ```bash
+   ./dev_deploy.sh -r 192.168.1.100  # Replace with your device IP
+   ```
+
+5. **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
+
+```bash
+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
+
+```bash
+# Edit Go files (config.go, web.go, etc.)
+./dev_deploy.sh -r 192.168.1.100 --skip-ui-build
+```
+
+### Run tests
+
+```bash
+./dev_deploy.sh -r 192.168.1.100 --run-go-tests
+```
+
+### 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"
+
+# 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
+
+1. **Update the Config struct in `config.go`:**
+
+   ```go
+   type Config struct {
+       // ... existing fields
+       NewFeatureEnabled bool `json:"new_feature_enabled"`
+   }
+   ```
+
+2. **Update the default configuration:**
+
+   ```go
+   var defaultConfig = &Config{
+       // ... existing defaults
+       NewFeatureEnabled: false,
+   }
+   ```
+
+3. **Add migration logic if needed for existing installations**
+
+
+---
+
+**Happy coding!**
+
+For more information, visit the [JetKVM Documentation](https://jetkvm.com/docs) or join our [Discord Server](https://jetkvm.com/discord).
--- a/README.md
+++ b/README.md
@ -37,7 +37,9 @@ JetKVM is written in Go & TypeScript. with some bits and pieces written in C. An

 The project contains two main parts, the backend software that runs on the KVM device and the frontend software that is served by the KVM device, and also the cloud.

-For most of local device development, all you need is to use the `./dev_deploy.sh` script. It will build the frontend and backend and deploy them to the local KVM device. Run `./dev_deploy.sh --help` for more information.
+For comprehensive development information, including setup, testing, debugging, and contribution guidelines, see **[DEVELOPMENT.md](DEVELOPMENT.md)**.
+
+For quick device development, use the `./dev_deploy.sh` script. It will build the frontend and backend and deploy them to the local KVM device. Run `./dev_deploy.sh --help` for more information.

 ## Backend

--- a/ui/package-lock.json
+++ b/ui/package-lock.json
@ -38,7 +38,7 @@
        "tailwind-merge": "^3.3.1",
        "usehooks-ts": "^3.1.1",
        "validator": "^13.15.15",
-        "zustand": "^4.5.2"
+        "zustand": "^5.0.6"
      },
      "devDependencies": {
        "@eslint/compat": "^1.3.1",
@ -1788,6 +1788,66 @@
        "node": ">=14.0.0"
      }
    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
+      "version": "1.4.3",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/wasi-threads": "1.0.2",
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
+      "version": "1.4.3",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
+      "version": "1.0.2",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
+      "version": "0.2.11",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/core": "^1.4.3",
+        "@emnapi/runtime": "^1.4.3",
+        "@tybys/wasm-util": "^0.9.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
+      "version": "0.9.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
+      "version": "2.8.0",
+      "dev": true,
+      "inBundle": true,
+      "license": "0BSD",
+      "optional": true
+    },
    "node_modules/@tailwindcss/oxide-win32-arm64-msvc": {
      "version": "4.1.11",
      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.1.11.tgz",
@ -7107,20 +7167,18 @@
      }
    },
    "node_modules/zustand": {
-      "version": "4.5.7",
-      "resolved": "https://registry.npmjs.org/zustand/-/zustand-4.5.7.tgz",
-      "integrity": "sha512-CHOUy7mu3lbD6o6LJLfllpjkzhHXSBlX8B9+qPddUsIfeF5S/UZ5q0kmCsnRqT1UHFQZchNFDDzMbQsuesHWlw==",
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/zustand/-/zustand-5.0.6.tgz",
+      "integrity": "sha512-ihAqNeUVhe0MAD+X8M5UzqyZ9k3FFZLBTtqo6JLPwV53cbRB/mJwBI0PxcIgqhBBHlEs8G45OTDTMq3gNcLq3A==",
      "license": "MIT",
-      "dependencies": {
-        "use-sync-external-store": "^1.2.2"
-      },
      "engines": {
-        "node": ">=12.7.0"
+        "node": ">=12.20.0"
      },
      "peerDependencies": {
-        "@types/react": ">=16.8",
+        "@types/react": ">=18.0.0",
        "immer": ">=9.0.6",
-        "react": ">=16.8"
+        "react": ">=18.0.0",
+        "use-sync-external-store": ">=1.2.0"
      },
      "peerDependenciesMeta": {
        "@types/react": {
@ -7131,6 +7189,9 @@
        },
        "react": {
          "optional": true
+        },
+        "use-sync-external-store": {
+          "optional": true
        }
      }
    }
--- a/ui/package.json
+++ b/ui/package.json
@ -49,7 +49,7 @@
    "tailwind-merge": "^3.3.1",
    "usehooks-ts": "^3.1.1",
    "validator": "^13.15.15",
-    "zustand": "^4.5.2"
+    "zustand": "^5.0.6"
  },
  "devDependencies": {
    "@eslint/compat": "^1.3.1",