N3XRemote – Remote Support

# N3XRemote — complete self-hosted remote support stack
#
#   signaling  WebSocket relay, Control API and browser Control Center
#   postgres   private device inventory, policy and audit database
#   coturn     TURN relay for restrictive/symmetric NATs
#
# Before you start:
#   1. point remote.example.com at this server (DNS A/AAAA record)
#      keep it DNS-only when the same hostname is also used for TURN
#   2. configure any reverse proxy to forward https://remote.example.com to http://127.0.0.1:8788
#      with WebSocket upgrades enabled; TLS/proxy is not part of this stack
#   3. when binding to 0.0.0.0, restrict port 8788 to your proxy/firewall
#   4. REQUIRED: publish TURN on your router/firewall or through a TCP/UDP layer 4 proxy
#      (not as a regular HTTP(S) proxy host):
#      3478/tcp, 3478/udp and 49160-49200/udp -> this Docker host
#      without these rules signaling works, but remote video/control cannot connect
#      for a second stack on the same host, set N3X_TURN_PORT and a separate
#      N3X_TURN_MIN_PORT/N3X_TURN_MAX_PORT range in Portainer or .env
#
# IMPORTANT — keep this file for future stack updates.
# POSTGRES_PASSWORD initializes only an empty postgres_data volume. Replacing
# it later requires changing the n3xremote database role password first, or
# removing postgres_data (which permanently deletes the Control Center data).
#
# Then run: docker compose up -d
# Control Center: https://remote.example.com/control-GENERATING/

services:
  signaling:
    image: ghcr.io/nexitpl/n3xremote-signaling:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      PORT: 8787
      TURN_SECRET: GENERATING_TURN_SECRET
      TURN_URL: turn:remote.example.com:${N3X_TURN_PORT:-3478}?transport=udp,turn:remote.example.com:${N3X_TURN_PORT:-3478}?transport=tcp
      DATABASE_URL: postgresql://n3xremote:GENERATING_DATABASE_PASSWORD@postgres:5432/n3xremote
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: GENERATING_ADMIN_PASSWORD
      ADMIN_PATH: /control-GENERATING
      SESSION_SECRET: GENERATING_SESSION_SECRET
    ports:
      - "127.0.0.1:8788:8787"
    networks:
      frontend:
      backend:

  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: n3xremote
      POSTGRES_USER: n3xremote
      POSTGRES_PASSWORD: GENERATING_DATABASE_PASSWORD
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "PGPASSWORD=$$POSTGRES_PASSWORD psql -h 127.0.0.1 -U $$POSTGRES_USER -d $$POSTGRES_DB -c 'SELECT 1' >/dev/null"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 10s
    networks:
      - backend

  coturn:
    image: coturn/coturn:4-alpine
    restart: unless-stopped
    network_mode: host
    environment:
      DETECT_EXTERNAL_IP: "yes"
      DETECT_RELAY_IP: "yes"
    command: >
      -n
      --log-file=stdout
      --realm=remote.example.com
      --use-auth-secret
      --static-auth-secret=GENERATING_TURN_SECRET
      --listening-port=${N3X_TURN_PORT:-3478}
      --min-port=${N3X_TURN_MIN_PORT:-49160}
      --max-port=${N3X_TURN_MAX_PORT:-49200}
      --no-tls
      --no-dtls
      --fingerprint
      --no-multicast-peers
      --no-cli
    tmpfs:
      - /var/lib/coturn

networks:
  frontend:
  backend:
    internal: true

volumes:
  postgres_data:

mkdir -p n3xremote && cd n3xremote
nano docker-compose.yml   # paste the file above
docker compose up -d

# Verify N3XRemote before configuring the proxy:
curl http://127.0.0.1:8788/healthz

# Configure your own reverse proxy (WebSockets required):
http://127.0.0.1:8788 -> https://remote.example.com

# REQUIRED TURN rules (direct NAT/firewall or a TCP/UDP layer 4 proxy):
# TCP 3478          -> DOCKER_HOST:3478
# UDP 3478          -> DOCKER_HOST:3478
# UDP 49160-49200   -> DOCKER_HOST:49160-49200

# Verify that coturn listens on the Docker host:
sudo ss -lntup | grep ':3478'

# Test TCP 3478 from a DIFFERENT internet connection, not this LAN:
nc -vz remote.example.com 3478

# Verify through the public proxy:
curl https://remote.example.com/healthz

# Open and bookmark the private Control Center address:
https://remote.example.com/control-GENERATING/

What to enter in the app's settings

Backend listener

127.0.0.1:8788

Reverse proxy target

http://127.0.0.1:8788

Signaling server

wss://remote.example.com

Control Center

https://remote.example.com/control-GENERATING/

Recovery owner

admin

Owner password

…

The downloaded app already uses remote.n3x.pl. Change the address only under Settings → Advanced when using your own instance. Keep the private Control Center address out of public documentation. Enroll unattended agents with the ready-made command generated in the panel; clients never receive TURN or database secrets.