Self-Hosted Tailscale DERP Relay Server

··

reads

AI Translation中文English

Key Insights

AI · GEN

Self-Hosted Tailscale DERP Relay Server

When using Tailscale's official DERP relay servers in China, you often encounter high latency and unstable connections. Self-hosting a DERP server on a VPS with a public IP can significantly improve communication latency between nodes and hole-punching success rate. Below are two Docker-based deployment methods: domain reverse proxy mode and pure IP mode.

Prerequisites

A VPS with a public IP (recommended to choose a region with low latency)
Docker and Docker Compose installed
Domain with DNS configured (required for Method 1, not for Method 2)
Nginx (or other reverse proxy) to handle SSL (required for Method 1, not for Method 2)

Method 1: Domain Deployment for DERP (Reverse Proxy Mode)

Docker Compose Configuration

Create docker-compose.yml:

CodeBlock Loading...

Key Configuration Explanation

Configuration Item	Description
network_mode: host	Required. Uses the host's network stack, supports IPv6 and STUN
DERP_DOMAIN	Your DERP server domain
DERP_ADDR	Listening address and port
DERPVERIFYCLIENTS	Set to true to verify client identity and prevent abuse
tailscaled.sock	Mount Tailscale socket for client verification

⚠️ Note: DERP_VERIFY_CLIENTS=true requires running the Tailscale client on the server and mounting its socket file.

Start Service

CodeBlock Loading...

Nginx Reverse Proxy Configuration

DERP uses WebSocket for communication, so the reverse proxy must be configured correctly.

CodeBlock Loading...

Important Configuration Explanations

Force WebSocket headers: proxy_set_header Upgrade "websocket" and Connection "upgrade" are required; otherwise, a 426 error will occur under HTTP/2
Use HTTP/1.1: proxy_http_version 1.1 ensures WebSocket works properly
Disable buffering: proxy_buffering off prevents relay data from being cached
Long timeout: 86400 seconds (24 hours) to keep connections from disconnecting

Reload Nginx:

CodeBlock Loading...

Tailscale ACL Configuration

CodeBlock Loading...

Configuration Explanation

Configuration Item	Description
OmitDefaultRegions	Set to true to disable official DERP and use only self-hosted
RegionID	Custom region ID, recommended to use 900+ to avoid conflicts
RegionCode	Region code, e.g., hkg, sgp, tyo
HostName	DERP server domain
DERPPort	DERP port, 443 after Nginx reverse proxy
STUNPort	STUN port, keep as 3478

Optional: Specify IP Address

If you don't want to use DNS resolution, you can specify the IP directly:

CodeBlock Loading...

Method 2: Domainless DERP Deployment (Pure IP Mode)

If you don't have a domain or don't want to deal with DNS and SSL certificates, you can deploy the DERP server directly using an IP address. This method uses the ip_derper image, which automatically generates a self-signed certificate without needing Nginx reverse proxy.

Docker Compose Configuration

Create docker-compose.yml:

CodeBlock Loading...

Key Configuration Explanation

Configuration Item	Description
ip_derper image	Modified from official derper, supports pure IP operation, automatically generates self-signed certificate
DERP_ADDR	Listening port, using 13477 here
DERP_CERTS	Self-signed certificate storage path (automatically generated inside container)
DERPVERIFYCLIENTS	Set to true to verify client identity and prevent abuse
network_mode: host	Uses the host's network stack, supports IPv6 and STUN

💡 Difference from the domain version: The domainless version does not require Nginx reverse proxy configuration; the DERP server directly exposes ports and uses self-signed TLS certificates.

Start Service

CodeBlock Loading...

ACL Configuration

CodeBlock Loading...

Core Configuration Explanation

Configuration Item	Description
OmitDefaultRegions	false means use both self-hosted and official DERP; true means only self-hosted
IPv4 / IPv6	Directly specify server IP address, no DNS resolution
InsecureForTests	Core configuration: set to true to allow skipping TLS certificate validation (due to self-signed certificate)
DERPPort	Matches the port in DERP_ADDR configuration, 13477 here
STUNPort	STUN port, default 3478; set to -1 to disable STUN for this node

⚠️ Note: Although InsecureForTests includes "ForTests" in the name, it is an official Tailscale configuration item to skip TLS validation, required in pure IP domainless scenarios.

Server Firewall Configuration

Regardless of the deployment method chosen, you must open the corresponding ports in the system firewall and cloud provider security groups (e.g., Alibaba Cloud, Tencent Cloud):

Method	Port	Protocol	Purpose
Method 1 (reverse proxy)	443	TCP	Nginx receives HTTPS/DERP traffic
Method 2 (pure IP)	13477	TCP	Native DERP Docker relay listening
All methods	3478	UDP	STUN protocol for NAT hole punching

CodeBlock Loading...

Verifying DERP Server

Check DERP Status

Run on any Tailscale client:

CodeBlock Loading...

The output should display your custom DERP region and its latency:

CodeBlock Loading...

Check Connection Method

CodeBlock Loading...

If it shows relay "hkg" or similar, it means your DERP relay is being used.

Common Issues

Q: Status shows IPv6: No

Check the following:

Does the server have an IPv6 address
Is DNS configured with AAAA records
Is Docker using network_mode: host
Is the firewall allowing IPv6

Q: 426 Upgrade Required Error

Nginx configuration issue, ensure:

proxy_set_header Upgrade "websocket" is set
proxy_set_header Connection "upgrade" is set
proxy_http_version 1.1 is used

Q: Client Verification Failed

Ensure:

Tailscale client is running on the server
/var/run/tailscale/tailscaled.sock is correctly mounted
The container has permission to access the socket

Summary

The main purposes of self-hosting a Tailscale DERP server:

Access private nodes, reduce remote communication latency.
Traffic does not go through official servers.
Optionally deploy nodes in specific regions like domestic cloud servers.
Supports IPv6, improving P2P hole-punching success probability.

Key configuration points:

Docker's network_mode must be set to host.
In domain reverse proxy mode, Nginx must include WebSocket headers (Upgrade "websocket" etc.) to avoid 426 errors.
In pure IP mode, ACL configuration must include "InsecureForTests": true.
OmitDefaultRegions in ACL controls whether to disable official DERP nodes.

Self-Hosted Tailscale DERP Relay Server

Prerequisites

A VPS with a public IP (recommended to choose a region with low latency)
Docker and Docker Compose installed
Domain with DNS configured (required for Method 1, not for Method 2)
Nginx (or other reverse proxy) to handle SSL (required for Method 1, not for Method 2)

Method 1: Domain Deployment for DERP (Reverse Proxy Mode)

Docker Compose Configuration

Create docker-compose.yml:

YAML

services:
  derper:
    container_name: derper
    image: fredliang/derper
    restart: always
    network_mode: host  # 直接使用宿主机网络，支持 IPv6
    environment:
      - DERP_DOMAIN=derp.example.com
      - DERP_ADDR=:13477
      - DERP_HTTP_PORT=13478
      - DERP_VERIFY_CLIENTS=true
    volumes:
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock

CodeBlock Loading...

Key Configuration Explanation

Configuration Item	Description
network_mode: host	Required. Uses the host's network stack, supports IPv6 and STUN
DERP_DOMAIN	Your DERP server domain
DERP_ADDR	Listening address and port
DERPVERIFYCLIENTS	Set to true to verify client identity and prevent abuse
tailscaled.sock	Mount Tailscale socket for client verification

⚠️ Note: DERP_VERIFY_CLIENTS=true requires running the Tailscale client on the server and mounting its socket file.

Start Service

BASH

docker compose up -d

CodeBlock Loading...

Nginx Reverse Proxy Configuration

DERP uses WebSocket for communication, so the reverse proxy must be configured correctly.

NGINX

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name derp.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location ^~ / {
        proxy_pass http://127.0.0.1:13477;
        
        # 核心：强制发送 WebSocket 头
        # 解决 HTTP/2 下头丢失导致 426 错误的问题
        proxy_set_header Upgrade "websocket";
        proxy_set_header Connection "upgrade";
        
        # 必须：协议版本与关闭缓存
        proxy_http_version 1.1;
        proxy_buffering off;
        
        # 基础头
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;
        
        # 超时（保持长连接）
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        
        # 安全头
        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
    }
}

CodeBlock Loading...

Important Configuration Explanations

Force WebSocket headers: proxy_set_header Upgrade "websocket" and Connection "upgrade" are required; otherwise, a 426 error will occur under HTTP/2
Use HTTP/1.1: proxy_http_version 1.1 ensures WebSocket works properly
Disable buffering: proxy_buffering off prevents relay data from being cached
Long timeout: 86400 seconds (24 hours) to keep connections from disconnecting

Reload Nginx:

BASH

sudo nginx -t && sudo nginx -s reload

CodeBlock Loading...

Tailscale ACL Configuration

JSON

{
  // 自定义 DERP 服务器
  "derpMap": {
    // 只使用自定义 DERP，禁用官方 DERP
    "OmitDefaultRegions": true,
    "Regions": {
      "900": {
        "RegionID": 900,
        "RegionCode": "hk",
        "RegionName": "DMIT Cloud Hong Kong",
        "Nodes": [
          {
            "Name": "hk1",
            "RegionID": 900,
            "HostName": "derp.example.com",
            "DERPPort": 443,
            "STUNPort": 3478
          }
        ]
      }
    }
  },
  "acls": [
    {
      "action": "accept",
      "src": ["*"],
      "dst": ["*:*"]
    }
  ]
}

CodeBlock Loading...

Configuration Explanation

Configuration Item	Description
OmitDefaultRegions	Set to true to disable official DERP and use only self-hosted
RegionID	Custom region ID, recommended to use 900+ to avoid conflicts
RegionCode	Region code, e.g., hkg, sgp, tyo
HostName	DERP server domain
DERPPort	DERP port, 443 after Nginx reverse proxy
STUNPort	STUN port, keep as 3478

Optional: Specify IP Address

If you don't want to use DNS resolution, you can specify the IP directly:

JSON

{
  "Name": "hk1",
  "RegionID": 900,
  "HostName": "derp.example.com",
  "IPv4": "[IP_ADDRESS]",
  "IPv6": "[IP_ADDRESS]",
  "DERPPort": 443,
  "STUNPort": 3478
}

CodeBlock Loading...

Method 2: Domainless DERP Deployment (Pure IP Mode)

Docker Compose Configuration

Create docker-compose.yml:

YAML

services:
  derper:
    container_name: derper
    image: ghcr.io/yangchuansheng/ip_derper:latest
    restart: always
    network_mode: host  # 直接使用宿主机网络，支持 IPv6
    environment:
      - DERP_HOST=你的服务器IP
      - DERP_ADDR=:13477
      - DERP_HTTP_PORT=13478
      - DERP_CERTS=/app/certs
      - DERP_STUN=true
      - DERP_VERIFY_CLIENTS=true
    volumes:
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock:ro
      - ./certs:/app/certs

CodeBlock Loading...

Key Configuration Explanation

Configuration Item	Description
ip_derper image	Modified from official derper, supports pure IP operation, automatically generates self-signed certificate
DERP_ADDR	Listening port, using 13477 here
DERP_CERTS	Self-signed certificate storage path (automatically generated inside container)
DERPVERIFYCLIENTS	Set to true to verify client identity and prevent abuse
network_mode: host	Uses the host's network stack, supports IPv6 and STUN

💡 Difference from the domain version: The domainless version does not require Nginx reverse proxy configuration; the DERP server directly exposes ports and uses self-signed TLS certificates.

Start Service

BASH

docker compose up -d

CodeBlock Loading...

ACL Configuration

JSON

{
  // 自定义 DERP 服务器
  "derpMap": {
    // 只使用自定义 DERP，禁用官方 DERP，true 是只使用自己的节点，false 是自己的节点+官方节点
    "OmitDefaultRegions": false,
    "Regions": {
      "900": {
        "RegionID":   900,
        "RegionCode": "chn",
        "RegionName": "China",
        "Nodes": [
          {
            "Name":     "server",
            "RegionID": 900,
            "IPv4":             "[IP_ADDRESS]",
            "IPv6":             "[IP_ADDRESS]",
            "InsecureForTests": true,
            "DERPPort":         13477,
            "STUNPort":         3478
          }
        ]
      }
    }
  }
}

CodeBlock Loading...

Core Configuration Explanation

Configuration Item	Description
OmitDefaultRegions	false means use both self-hosted and official DERP; true means only self-hosted
IPv4 / IPv6	Directly specify server IP address, no DNS resolution
InsecureForTests	Core configuration: set to true to allow skipping TLS certificate validation (due to self-signed certificate)
DERPPort	Matches the port in DERP_ADDR configuration, 13477 here
STUNPort	STUN port, default 3478; set to -1 to disable STUN for this node

⚠️ Note: Although InsecureForTests includes "ForTests" in the name, it is an official Tailscale configuration item to skip TLS validation, required in pure IP domainless scenarios.

Server Firewall Configuration

Regardless of the deployment method chosen, you must open the corresponding ports in the system firewall and cloud provider security groups (e.g., Alibaba Cloud, Tencent Cloud):

Method	Port	Protocol	Purpose
Method 1 (reverse proxy)	443	TCP	Nginx receives HTTPS/DERP traffic
Method 2 (pure IP)	13477	TCP	Native DERP Docker relay listening
All methods	3478	UDP	STUN protocol for NAT hole punching

BASH

# UFW example: Method 1 (reverse proxy deployment, allow HTTPS)
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp

# UFW example: Method 2 (pure IP deployment, direct allow)
sudo ufw allow 13477/tcp
sudo ufw allow 3478/udp

CodeBlock Loading...

Verifying DERP Server

Check DERP Status

Run on any Tailscale client:

BASH

tailscale netcheck

CodeBlock Loading...

The output should display your custom DERP region and its latency:

TEXT

Report:
    * UDP: true
    * IPv4: yes, ...
    * IPv6: yes, ...
    * DERP latency:
        - hkg: 25.3ms (Tencent Cloud Hong Kong)

CodeBlock Loading...

Check Connection Method

BASH

tailscale status

CodeBlock Loading...

If it shows relay "hkg" or similar, it means your DERP relay is being used.

Common Issues

Q: Status shows IPv6: No

Check the following:

Does the server have an IPv6 address
Is DNS configured with AAAA records
Is Docker using network_mode: host
Is the firewall allowing IPv6

Q: 426 Upgrade Required Error

Nginx configuration issue, ensure:

proxy_set_header Upgrade "websocket" is set
proxy_set_header Connection "upgrade" is set
proxy_http_version 1.1 is used

Q: Client Verification Failed

Ensure:

Tailscale client is running on the server
/var/run/tailscale/tailscaled.sock is correctly mounted
The container has permission to access the socket

Summary

The main purposes of self-hosting a Tailscale DERP server:

Access private nodes, reduce remote communication latency.
Traffic does not go through official servers.
Optionally deploy nodes in specific regions like domestic cloud servers.
Supports IPv6, improving P2P hole-punching success probability.

Key configuration points:

Docker's network_mode must be set to host.
In domain reverse proxy mode, Nginx must include WebSocket headers (Upgrade "websocket" etc.) to avoid 426 errors.
In pure IP mode, ACL configuration must include "InsecureForTests": true.
OmitDefaultRegions in ACL controls whether to disable official DERP nodes.