NetDesk 1.5.0 — source release

docker/.env.example

@@ -0,0 +1,39 @@
+# NetDesk server config — copy to `.env` and fill in. `.env` is gitignored.
+# Every value is optional; the server runs with sensible defaults, but you want
+# at least a status key + portal password + TURN secret for a real deployment.
+
+# Public port to publish the server on (maps to container :8443).
+ND_PORT=8443
+
+# Secret required to read /status details (pick a long random string).
+ND_STATUS_KEY=
+
+# Secret hosts must present to register (recommended; blocks stranger hosts).
+ND_REG_KEY=
+
+# Password for the web management portal (/portal).
+ND_PORTAL_PASSWORD=
+
+# Email granted unrestricted access + the admin panel.
+ND_OWNER_EMAIL=
+
+# Public base URL used in verification emails, e.g. https://netdesk.example.com
+ND_PUBLIC_URL=
+
+# Email accounts (optional): sender address + SMTP relay for verification mail.
+ND_MAIL_FROM=
+ND_SMTP_HOST=127.0.0.1
+
+# Self-hosted coturn (optional): the server mints 12h HMAC TURN creds against
+# this secret; the coturn sidecar shares it. TURN_REALM is the coturn realm.
+ND_TURN_HOST=
+ND_TURN_SECRET=
+TURN_REALM=netdesk.local
+
+# In-process TLS (optional): paths INSIDE the container (mount certs in compose).
+# Usually you terminate TLS at a reverse proxy instead and leave these blank.
+ND_CERT=
+ND_KEY=
+
+# Set to 1 for debug logging.
+ND_VERBOSE=0

docker/Dockerfile

@@ -0,0 +1,29 @@
+# NetDesk signaling/relay server — container image.
+# Build context is the repo root (so it can copy server/):
+#   docker build -f docker/Dockerfile -t netdesk-server .
+# or just `docker compose up -d --build` from docker/.
+FROM python:3.12-slim
+
+# aiohttp + cryptography (the server's only third-party deps). Pinned to the
+# versions the production host runs.
+RUN pip install --no-cache-dir aiohttp==3.9.1 cryptography==41.0.7
+
+WORKDIR /app/server
+# Server code + the web assets it serves (web/ is resolved relative to the
+# script, so it must sit next to netdesk_server.py).
+COPY server/netdesk_server.py /app/server/netdesk_server.py
+COPY server/web /app/server/web
+
+# Persistent state (accounts.db, audit.log, files/) lives on a mounted volume,
+# kept OUT of the image + the code dir via ND_DATA_DIR (see _nd_data_root()).
+ENV ND_DATA_DIR=/data
+RUN mkdir -p /data
+VOLUME ["/data"]
+
+COPY docker/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+# The server listens on 8443 (plain HTTP/WS; terminate TLS at a reverse proxy,
+# or pass ND_CERT/ND_KEY to enable TLS in-process).
+EXPOSE 8443
+ENTRYPOINT ["docker-entrypoint.sh"]

docker/README.md

@@ -0,0 +1,41 @@
+# NetDesk server — Docker
+
+Run a full self-hosted NetDesk (signaling + relay + web viewer/host + accounts +
+portal + audit) with one command, plus an optional coturn TURN sidecar.
+
+```sh
+cd docker
+cp .env.example .env     # then edit .env — at least ND_STATUS_KEY + ND_PORTAL_PASSWORD
+docker compose up -d --build
+```
+
+The server listens on `:8443` (plain HTTP/WS). For the public internet, terminate
+TLS at a reverse proxy (nginx/Caddy/Traefik) in front of it, or set `ND_CERT` /
+`ND_KEY` in `.env` (and mount the certs in `docker-compose.yml`) to run TLS
+in-process.
+
+Quick check once it's up:
+
+```sh
+curl "http://localhost:8443/status?token=$ND_STATUS_KEY"
+```
+
+## Persistence
+
+All state — `accounts.db`, `audit.log`, and uploaded `files/` — lives in the
+named volume `netdesk-data` (mounted at `/data` via `ND_DATA_DIR`), so it
+survives `docker compose down` / image rebuilds. Back it up with
+`docker run --rm -v netdesk-data:/data -v "$PWD":/backup busybox tar czf /backup/netdesk-data.tgz -C /data .`.
+
+## Config
+
+Everything is set through `.env` (see `.env.example` for the full list); the
+entrypoint maps `ND_*` vars to the server's CLI flags. Only non-empty vars are
+passed, so the defaults apply otherwise.
+
+## TURN
+
+The `coturn` sidecar runs with `--use-auth-secret` sharing `ND_TURN_SECRET`; the
+server mints 12-hour HMAC credentials against the same secret. It uses host
+networking because TURN needs the real relay port range. Leave `ND_TURN_HOST` /
+`ND_TURN_SECRET` blank to disable TURN (direct P2P + the WSS relay still work).

docker/docker-compose.yml

@@ -0,0 +1,44 @@
+# NetDesk self-hosted stack: the signaling/relay/web server + a coturn TURN
+# sidecar. One command to stand up a full self-hosted NetDesk:
+#
+#   cd docker && cp .env.example .env    # then edit .env (secrets)
+#   docker compose up -d --build
+#
+# Terminate TLS at your reverse proxy (nginx/Caddy/Traefik) in front of :8443,
+# or set ND_CERT/ND_KEY + mount the certs to run TLS in-process.
+services:
+  netdesk:
+    build:
+      context: ..                 # repo root, so the image can COPY server/
+      dockerfile: docker/Dockerfile
+    image: netdesk-server:latest
+    restart: unless-stopped
+    ports:
+      - "${ND_PORT:-8443}:8443"   # HTTP/WS (put a TLS proxy in front for the internet)
+    env_file: .env
+    volumes:
+      - netdesk-data:/data        # accounts.db, audit.log, files/ (ND_DATA_DIR)
+    # If you enable in-process TLS, also mount your certs and set ND_CERT/ND_KEY:
+    #   - ./certs:/certs:ro
+
+  # Self-hosted TURN (use-auth-secret): the server mints 12h HMAC creds against
+  # ND_TURN_SECRET, and peers relay through here when direct P2P can't punch NAT.
+  # Set ND_TURN_HOST + ND_TURN_SECRET in .env (and TURN_REALM) to activate it.
+  coturn:
+    image: coturn/coturn:4.6.2
+    restart: unless-stopped
+    network_mode: host           # TURN needs the real host ports / relay range
+    command:
+      - -n
+      - --use-auth-secret
+      - --static-auth-secret=${ND_TURN_SECRET:-changeme}
+      - --realm=${TURN_REALM:-netdesk.local}
+      - --listening-port=3478
+      - --tls-listening-port=5349
+      - --min-port=49152
+      - --max-port=65535
+      - --no-cli
+      - --fingerprint
+
+volumes:
+  netdesk-data:

docker/docker-entrypoint.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+# Map ND_* environment variables to netdesk_server.py CLI flags, so secrets stay
+# out of the image and the compose file (they come from the .env file / the
+# environment). Only non-empty vars are passed, so every flag is optional.
+set -eu
+
+set -- --port "${ND_PORT:-8443}" --bind "${ND_BIND:-0.0.0.0}"
+
+[ -n "${ND_STATUS_KEY:-}" ]      && set -- "$@" --status-key "$ND_STATUS_KEY"
+[ -n "${ND_REG_KEY:-}" ]         && set -- "$@" --reg-key "$ND_REG_KEY"
+[ -n "${ND_PORTAL_PASSWORD:-}" ] && set -- "$@" --portal-password "$ND_PORTAL_PASSWORD"
+[ -n "${ND_ACCESS_PATH:-}" ]     && set -- "$@" --access-path "$ND_ACCESS_PATH"
+[ -n "${ND_OWNER_EMAIL:-}" ]     && set -- "$@" --owner-email "$ND_OWNER_EMAIL"
+[ -n "${ND_PUBLIC_URL:-}" ]      && set -- "$@" --public-url "$ND_PUBLIC_URL"
+[ -n "${ND_MAIL_FROM:-}" ]       && set -- "$@" --mail-from "$ND_MAIL_FROM"
+[ -n "${ND_SMTP_HOST:-}" ]       && set -- "$@" --smtp-host "$ND_SMTP_HOST"
+[ -n "${ND_TURN_HOST:-}" ]       && set -- "$@" --turn-host "$ND_TURN_HOST"
+[ -n "${ND_TURN_SECRET:-}" ]     && set -- "$@" --turn-secret "$ND_TURN_SECRET"
+[ "${ND_ALWAYS_USE_RELAY:-0}" = "1" ] && set -- "$@" --always-use-relay
+[ -n "${ND_CERT:-}" ]            && set -- "$@" --cert "$ND_CERT"
+[ -n "${ND_KEY:-}" ]             && set -- "$@" --key "$ND_KEY"
+[ "${ND_VERBOSE:-0}" = "1" ]     && set -- "$@" --verbose
+
+# ND_TURN_* for Cloudflare TURN are read from the environment by the server
+# itself (argparse defaults to os.environ), so they need no mapping here.
+
+echo "[entrypoint] exec python netdesk_server.py $*"
+exec python /app/server/netdesk_server.py "$@"