N3X Remote – 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
    environment:
      # Set N3X_TURN_EXTERNAL_IP only when automatic DNS detection is blocked.
      REAL_EXTERNAL_IP: ${N3X_TURN_EXTERNAL_IP:-}
    ports:
      - "${N3X_TURN_PORT:-3478}:${N3X_TURN_PORT:-3478}/tcp"
      - "${N3X_TURN_PORT:-3478}:${N3X_TURN_PORT:-3478}/udp"
      - "${N3X_TURN_MIN_PORT:-49160}-${N3X_TURN_MAX_PORT:-49200}:${N3X_TURN_MIN_PORT:-49160}-${N3X_TURN_MAX_PORT:-49200}/udp"
    entrypoint: ["/bin/sh", "-ec"]
    command:
      - |
        candidate="$${REAL_EXTERNAL_IP:-}"
        if [ -z "$$candidate" ]; then
          candidate="$$(detect-external-ip 2>/dev/null || true)"
        fi
        external_ip="$$(printf '%s\n' "$$candidate" | awk 'match($$0, /([0-9]{1,3}\.){3}[0-9]{1,3}/) { print substr($$0, RSTART, RLENGTH); exit }')"
        if [ -z "$$external_ip" ]; then
          echo "N3XRemote coturn: no valid public IPv4 address was detected; set N3X_TURN_EXTERNAL_IP" >&2
          exit 1
        fi
        echo "N3XRemote coturn: using external IPv4 $$external_ip"
        exec turnserver \
          -n \
          --log-file=stdout \
          --external-ip="$$external_ip" \
          --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 \
          --fingerprint \
          --no-multicast-peers
    tmpfs:
      - /var/lib/coturn
    networks:
      - frontend

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 is running and listens on the Docker host:
docker compose ps coturn
docker compose logs --tail=100 coturn
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.