Merge 57fbee1490 into 55fbd6c359

* 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.

.github/workflows/push.yaml

@@ -0,0 +1,126 @@
+name: Push
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  id-token: write
+  contents: read
+  pull-requests: write
+
+jobs:
+  build:
+    name: Build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04]
+        go: [1.21, 1.23.4]
+        node: [21]
+        goos: [linux]
+        goarch: [arm]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Install Dependencies
+        working-directory: ui
+        run: npm ci
+
+      - name: Build UI
+        working-directory: ui
+        run: npm run build:device
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+
+      - name: Install Go Dependencies
+        run: |
+          go mod download
+
+      - name: Build Binaries
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: |
+          GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w -X kvm.builtAppVersion=dev-${GIT_COMMIT:0:7}" -o bin/jetkvm_app cmd/main.go
+          chmod 755 bin/jetkvm_app
+
+      - name: Upload Debug Artifact
+        uses: actions/upload-artifact@v4
+        if: ${{ (github.ref == 'refs/heads/main' || github.event_name == 'pull_request') && matrix.go == '1.21' }}
+        with:
+          name: jetkvm_app_debug
+          path: bin/jetkvm_app
+
+  comment:
+    name: Comment
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Generate Links
+        id: linksa
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ARTIFACT_ID=$(gh api repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts --jq '.artifacts[0].id')
+          echo "ARTIFACT_URL=https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts/$ARTIFACT_ID" >> $GITHUB_ENV
+          echo "LATEST_COMMIT=$(git rev-parse --short HEAD)" >> $GITHUB_ENV
+
+      - name: Comment on PR
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            TITLE="${{ github.event.pull_request.title }}"
+            PR_NUMBER=${{ github.event.pull_request.number }}
+          else
+            TITLE="main branch"
+          fi
+
+          COMMENT=$(cat << EOF
+          ✅ **Build successfully for $TITLE!**
+
+          | Name             | Link                                                                 |
+          |------------------|----------------------------------------------------------------------|
+          | 🔗 Debug Binary  | [Download](${{ env.ARTIFACT_URL }})                                   |
+          | 🔗 Latest commit | [${{ env.LATEST_COMMIT }}](https://github.com/${{ github.repository }}/commit/${{ github.sha }}) |
+          EOF
+          )
+
+          # Post Comment
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            # Look for an existing comment
+            COMMENT_ID=$(gh api repos/${{ github.repository }}/issues/$PR_NUMBER/comments \
+              --jq '.[] | select(.body | contains("✅ **Build successfully for")) | .id')
+
+            if [ -z "$COMMENT_ID" ]; then
+              # Create a new comment if none exists
+              gh pr comment $PR_NUMBER --body "$COMMENT"
+            else
+              # Update the existing comment
+              gh api repos/${{ github.repository }}/issues/comments/$COMMENT_ID \
+                --method PATCH \
+                -f body="$COMMENT"
+            fi
+          else
+            # Log the comment for main branch
+            echo "$COMMENT"
+          fi

.github/workflows/release.yaml

@@ -0,0 +1,91 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 21
+
+      - name: Install Dependencies
+        working-directory: ui
+        run: npm ci
+
+      - name: Build UI
+        working-directory: ui
+        run: npm run build:device
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.21
+
+      - name: Build Release Binaries
+        env:
+          REF: ${{ github.ref }}
+        run: |
+          GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w -X kvm.builtAppVersion=${REF:11}" -o bin/jetkvm_app cmd/main.go
+          chmod 755 bin/jetkvm_app
+
+      - name: Create checksum
+        env:
+          REF: ${{ github.ref }}
+        run: |
+          SUM=$(shasum -a 256 bin/jetkvm_app | cut -d ' ' -f 1)
+          echo -e "\n#### SHA256 Checksum\n\`\`\`\n$SUM  bin/jetkvm_app\n\`\`\`\n" >> ./RELEASE_CHANGELOG
+          echo -e "$SUM bin/jetkvm_app\n" > checksums.txt
+
+      - name: Create Release Branch
+        env:
+          REF: ${{ github.ref }}
+        run: |
+          BRANCH=release/${REF:10}
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git checkout -b ${BRANCH}
+          git push -u origin ${BRANCH}
+
+      - name: Create Release
+        id: create_release
+        uses: softprops/action-gh-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          draft: true
+          prerelease: ${{ contains(github.ref, 'rc') || contains(github.ref, 'beta') || contains(github.ref, 'alpha') }}
+          body_path: ./RELEASE_CHANGELOG
+
+      - name: Upload JetKVM binary
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: bin/jetkvm_app
+          asset_name: jetkvm_app
+          asset_content_type: application/octet-stream
+
+      - name: Upload checksum
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: ./checksums.txt
+          asset_name: checksums.txt
+          asset_content_type: text/plain

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).

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