add docs, protocol, plugins, README, CHANGELOG

2026-07-09 12:30:55 +02:00 · 2026-07-09 12:30:55 +02:00 · f262da222b
commit f262da222b
parent 1d2209bfac
44 changed files with 9269 additions and 0 deletions
--- a/docs/03-server/deployment.md
+++ b/docs/03-server/deployment.md
@ -0,0 +1,221 @@
+# Deployment
+
+> **Phase 1 note:** published container images and HTTP health checks are not available yet.
+> For local development, build from source and use [dev/README.md](../../dev/README.md).
+
+## Option A - Docker (when images are published)
+
+The fastest way to get a node running once official images exist.
+
+### Prerequisites
+
+- Docker 24+
+- Docker Compose v2
+
+### docker-compose.yml
+
+```yaml
+version: "3.9"
+
+services:
+  gateway:
+    # Build locally until ghcr.io/vnox images are published:
+    # build: { context: ../.., dockerfile: docker/gateway.Dockerfile }
+    image: ghcr.io/vnox/gateway:latest
+    restart: unless-stopped
+    ports:
+      - "7600:7600"         # TCP — client connections
+    volumes:
+      - ./config.toml:/etc/vnox/config.toml:ro
+      - vnox-data:/var/lib/vnox
+    environment:
+      - VNOX_LOG=info
+
+  voice-node:
+    image: ghcr.io/vnox/voice-node:latest
+    restart: unless-stopped
+    ports:
+      - "7700:7700/udp"     # UDP — voice packets
+    volumes:
+      - ./config.toml:/etc/vnox/config.toml:ro
+    environment:
+      - VNOX_LOG=info
+
+volumes:
+  vnox-data:
+```
+
+### Start
+
+```bash
+docker compose up -d
+docker compose logs -f
+```
+
+### Verify
+
+```bash
+# Phase 1: no /health endpoint yet. Check TCP instead:
+nc -zv localhost 7600
+
+# Or watch gateway logs after start:
+# VNOX_LOG=info cargo run -p vnox-gateway -- --config dev/config.toml
+```
+
+When an HTTP health endpoint ships (Phase 2), it may look like:
+
+```bash
+curl http://localhost:7600/health
+# {"status":"ok","version":"LNEx v1","node":"your-node-name"}
+```
+
+---
+
+## Option B - systemd (bare binary)
+
+For servers where Docker is not available or not desired.
+
+### Download
+
+```bash
+# Replace VERSION with the latest release tag
+VERSION=0.1.0
+curl -L https://github.com/vnox/vnox/releases/download/v${VERSION}/vnox-linux-x86_64.tar.gz \
+  | tar xz -C /usr/local/bin/
+```
+
+Binaries installed:
+- `/usr/local/bin/vnox-gateway`
+- `/usr/local/bin/vnox-voice-node`
+
+### Config
+
+```bash
+mkdir -p /etc/vnox /var/lib/vnox
+cp config.example.toml /etc/vnox/config.toml
+$EDITOR /etc/vnox/config.toml
+```
+
+### systemd units
+
+`/etc/systemd/system/vnox-gateway.service`:
+
+```ini
+[Unit]
+Description=VNOX Gateway
+After=network.target
+
+[Service]
+ExecStart=/usr/local/bin/vnox-gateway --config /etc/vnox/config.toml
+Restart=on-failure
+RestartSec=5s
+User=vnox
+Group=vnox
+StateDirectory=vnox
+RuntimeDirectory=vnox
+
+[Install]
+WantedBy=multi-user.target
+```
+
+`/etc/systemd/system/vnox-voice-node.service`:
+
+```ini
+[Unit]
+Description=VNOX Voice Node
+After=network.target vnox-gateway.service
+
+[Service]
+ExecStart=/usr/local/bin/vnox-voice-node --config /etc/vnox/config.toml
+Restart=on-failure
+RestartSec=5s
+User=vnox
+Group=vnox
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Enable and start
+
+```bash
+# Create service user
+useradd -r -s /sbin/nologin vnox
+
+# Enable services
+systemctl daemon-reload
+systemctl enable --now vnox-gateway vnox-voice-node
+
+# Check status
+systemctl status vnox-gateway
+systemctl status vnox-voice-node
+```
+
+---
+
+## Option C - bare binary (dev / test)
+
+For local development and testing without systemd, see [dev/README.md](../../dev/README.md).
+
+```bash
+# Terminal 1 - gateway
+cargo run -p vnox-gateway -- --config dev/config.toml
+
+# Terminal 2 - voice node
+cargo run -p vnox-voice-node -- --config dev/config.toml
+```
+
+---
+
+## Minimal config.toml
+
+The minimum required configuration to get a node running:
+
+```toml
+[node]
+name    = "my-node"           # displayed to clients
+address = "my-node.example.com"  # public address (domain or IP)
+
+[gateway]
+bind = "0.0.0.0:7600"
+
+[voice]
+bind = "0.0.0.0:7700"
+
+[identity]
+# Generated on first start if not present
+# keypair_path = "/var/lib/vnox/node.key"
+```
+
+See [configuration.md](configuration.md) for the full reference.
+
+---
+
+## Firewall
+
+Open the following ports:
+
+```bash
+# TCP — client connections
+ufw allow 7600/tcp
+
+# UDP — voice packets
+ufw allow 7700/udp
+```
+
+If running behind a reverse proxy (nginx / caddy), only expose port 443 externally
+and proxy to 7600 internally. UDP 7700 must be directly accessible.
+
+---
+
+## First connection test
+
+1. Download the VNOX client
+2. Open VNOX → Add node → enter your server address
+3. The client will generate an identity on first launch
+4. Connect — you should see your node's channels
+
+If connection fails, check:
+- gateway is running: `systemctl status vnox-gateway`
+- port 7600 is open: `nc -zv your-server 7600`
+- logs: `journalctl -u vnox-gateway -f`