Self-hosting
Configuration
Relay and deployment environment variables.
The Relay is configured purely from environment variables — there is no config
file. In the Compose unit these are supplied from deploy/.env.
Relay environment
| Variable | Default | Purpose |
|---|---|---|
PORT | 8080 | HTTP listen port |
DB_PATH | <temp>/nodus-relay/relay.db | SQLite database file |
REDIS_URL | redis://localhost:6379/0 | Redis connection |
SESSION_COOKIE_NAME | nodus_session | Session cookie name |
SESSION_MAX_AGE_DAYS | 30 | Session lifetime |
SESSION_TOUCH_INTERVAL_MINUTES | 30 | How often session expiry is extended |
SESSION_COOKIE_SECURE | true | Set false only for plain-HTTP dev |
SESSION_COOKIE_DOMAIN | (empty) | Parent domain for split-origin cookies (e.g. .nodus.example.com) |
ALLOWED_ORIGINS | http://localhost:3000,http://127.0.0.1:3000 | Origins allowed to open the Relay WebSocket |
BUFFER_DIR | <temp>/nodus-relay/buffer | Transient encrypted shard buffer |
BUFFER_TTL_HOURS | 72 | How long buffered shards live |
MAX_SHARD_BYTES_MB | 32 | Largest plaintext shard buffered |
TRUST_PROXY | false | Trust X-Forwarded-For (enable behind a proxy) |
EXPO_PUSH_ACCESS_TOKEN | (empty) | Expo push; empty disables auth |
VAPID_PUBLIC_KEY | (empty) | Web Push; both keys required to enable |
VAPID_PRIVATE_KEY | (empty) | Web Push private key |
VAPID_SUBJECT | mailto:admin@example.com | VAPID contact |
Deployment environment (deploy/.env)
| Variable | Purpose |
|---|---|
WEB_HOST | Web app hostname; Caddy gets TLS automatically |
RELAY_HOST | Relay hostname used by the browser WebSocket, mobile, and Storage Nodes |
DOCS_HOST | Documentation hostname |
PUBLIC_RELAY_URL | Relay origin shown to users/nodes for pairing |
NEXT_PUBLIC_RELAY_URL | Browser WebSocket target; inlined into the web bundle at build time |
ALLOWED_ORIGINS | Must exactly match the browser origin |
SESSION_COOKIE_SECURE | true for HTTPS, false for local HTTP |
SESSION_COOKIE_DOMAIN | Parent domain shared by the web and Relay hosts, e.g. .nodus.example.com |
REDIS_PASSWORD | Redis password (required, URL-safe) |
BUFFER_TTL_HOURS | Passed to the Relay |
MAX_SHARD_BYTES_MB | Passed to the Relay (must cover client shard size) |
EXPO_PUSH_ACCESS_TOKEN | Optional mobile push |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT | Web Push |
NEXT_PUBLIC_VAPID_PUBLIC_KEY | Build arg for the web image; must match VAPID_PUBLIC_KEY |
TRUST_PROXY is intentionally absent from .env.example; Compose pins it to
"true" because Caddy always fronts the Relay.
Client and node configuration
Web, mobile, and Storage Node variables are listed in Reference → Configuration.