DERP Relay Server Deployment

Overview

DERP (Designated Encrypted Relay for Packets) is a relay server that forwards WireGuard packets over WebSocket in environments where direct UDP connections cannot be established (Symmetric NAT, CGNAT, strict firewalls).

Nefia uses the public relay at relay.nefia.ai by default, but self-hosting a DERP server is recommended in the following cases:

• Latency optimization — Place the relay geographically close to your users
• Privacy requirements — Ensure traffic only passes through your own infrastructure
• Availability requirements — Eliminate dependency on the public relay
• ACL control — Allow connections only from authorized WireGuard public keys

Agent ──── wss:// ───→ DERP Relay ←── wss:// ──── Operator
             (WebSocket relay, encrypted WireGuard packets)

Docker Deployment

Building the Image

Build the image using the deploy/derp/Dockerfile included in the repository:

docker build -t nefia-derp:latest -f deploy/derp/Dockerfile .

This multi-stage build:

1. Statically compiles nefia-derp with Go 1.25
2. Deploys onto a distroless (nonroot) base image
3. Exposes port 8443

Basic Startup

docker run -d \
  --name nefia-derp \
  -p 8443:8443 \
  -e NEFIA_DERP_METRICS_TOKEN="$(openssl rand -base64 32)" \
  nefia-derp:latest

docker-compose.yml

Example configuration for production environments:

services:
  nefia-derp:
    image: nefia-derp:latest
    build:
      context: .
      dockerfile: deploy/derp/Dockerfile
    ports:
      - "8443:8443"
      - "127.0.0.1:9090:9090"  # Prometheus metrics (local only)
    environment:
      NEFIA_DERP_METRICS_TOKEN: "${DERP_METRICS_TOKEN}"
    command:
      - "--addr=:8443"
      - "--max-clients=10000"
      - "--metrics-port=9090"
      - "--allowed-keys-file=/etc/nefia/allowed-keys.txt"
    volumes:
      - ./allowed-keys.txt:/etc/nefia/allowed-keys.txt:ro
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 256M
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8443/healthz"]
      interval: 15s
      timeout: 5s
      retries: 3

Fly.io Deployment

You can deploy to Fly.io using the deploy/derp/fly.toml included in the repository.

fly apps create nefia-derp --machines

fly secrets set NEFIA_DERP_METRICS_TOKEN="$(openssl rand -base64 32)" --app nefia-derp

fly deploy --config deploy/derp/fly.toml

# Tokyo (default primary_region)
# US East
fly scale count 1 --region iad --app nefia-derp
# EU West
fly scale count 1 --region cdg --app nefia-derp
# Southeast Asia
fly scale count 1 --region sin --app nefia-derp

Key Fly.io configuration points:

Configuration Flags

Rate Limiting

The DERP server has IP-based rate limiting enabled by default:

Health Check

The DERP server provides a health check via the /healthz endpoint.

Without Authentication

curl http://localhost:8443/healthz

Returns only a minimal status (ok / error).

With Authentication (Including Metrics)

curl -H "Authorization: Bearer $METRICS_TOKEN" http://localhost:8443/healthz

Returns a response with detailed metrics including active client count, packet statistics, and memory usage.

Prometheus Monitoring

When the --metrics-port flag is specified, a Prometheus metrics endpoint is enabled at 127.0.0.1:<port>/metrics.

nefia-derp --addr :8443 --metrics-port 9090

Example Prometheus scrape_configs configuration:

scrape_configs:
  - job_name: "nefia-derp"
    static_configs:
      - targets: ["localhost:9090"]

Key metrics:

ACL (Access Control List)

You can restrict connections to only the WireGuard public keys listed in the file specified by --allowed-keys-file.

allowed-keys.txt Format

# Operator's public key
dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGtleQ==
 
# Agent: web-01
YW5vdGhlciBiYXNlNjQgZW5jb2RlZCBrZXk=
 
# Agent: db-01
eWV0IGFub3RoZXIgYmFzZTY0IGVuY29kZWQ=

• One base64-encoded WireGuard public key per line
• Lines starting with # are comments
• Blank lines are ignored
• Keys are 32-byte base64-encoded

To check the operator's public key:

nefia vpn status

The agent's public key can be found in the vpn.public_key field within the host definition in nefia.yaml.

TLS Termination

nefia-derp itself does not perform TLS termination. Use one of the following methods to provide TLS:

• Fly.io — Automatic TLS termination (no additional configuration needed)
• Load Balancer — AWS ALB, GCP Load Balancer, Cloudflare, etc.
• Reverse Proxy — nginx, Caddy, etc.

Example nginx reverse proxy configuration:

server {
    listen 443 ssl http2;
    server_name derp.example.com;
 
    ssl_certificate     /etc/letsencrypt/live/derp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/derp.example.com/privkey.pem;
 
    location /derp {
        proxy_pass http://127.0.0.1:8443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400s;
    }
 
    location /healthz {
        proxy_pass http://127.0.0.1:8443;
    }
}

Enable the --trust-proxy flag when using a reverse proxy.

Operator-Side Configuration

To use a deployed DERP server, add the DERP server URL to the operator's nefia.yaml:

vpn:
  derp_servers:
    - url: "wss://derp.example.com/derp"
      region: "ap-northeast-1"

Security Considerations

Troubleshooting

Next Steps