VNOX-Server/docs/03-server/deployment.md

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.

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

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

docker compose up -d
docker compose logs -f

Verify

# 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:

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

# 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

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:

[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:

[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

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

# 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:

[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 for the full reference.

---

Firewall

Open the following ports:

# 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