Deploy Tailscale Derper Self-Hosted Relay Server

Tailscale is a convenient mesh networking tool that connects devices across different networks, even different countries, into a single virtual LAN. When P2P hole punching fails, traffic is relayed through Tailscale’s DERP (Designated Encrypted Relay for Packets) nodes.

Since official DERP servers are primarily located outside certain regions, relay latency can be very high in some network environments, severely impacting user experience. By self-hosting a DERP server, you can significantly reduce relay latency and improve access speed.

Prerequisites#

Before starting deployment, you need:

Server: A server with a public IP address (preferably close to your usage region)
Domain: A domain name pointing to your server (e.g., derper.example.com)
Firewall Configuration: Open the following ports
- TCP 80 (HTTP, for certificate validation)
- TCP 443 (HTTPS, DERP service)
- UDP 3478 (STUN hole punching)

If using a server in mainland China, the domain must complete ICP filing to use ports 80 and 443.

Method 1: Docker Deployment (Recommended)#

Docker deployment is simpler and faster, suitable for most users. We’ll use the fredliang/derper image, a pre-packaged Derper Docker image.

Install Docker#

If Docker and Docker Compose are not installed on your server, install them first:

1
# Install Docker (Ubuntu example)
2
curl -fsSL https://get.docker.com | bash
3

4
# Start Docker service
5
sudo systemctl enable docker
6
sudo systemctl start docker

Create Docker Compose Configuration#

Create a working directory and write docker-compose.yml:

1
mkdir -p /opt/derper
2
cd /opt/derper

Create docker-compose.yml file:

1
version: '3.8'
2
services:
3
  derper:
4
    image: fredliang/derper
5
    container_name: derper
6
    restart: always
7
    environment:
8
      - DERP_CERT_MODE=manual  # Use manual certificates
9
      - DERP_ADDR=:443  # DERP service port
10
      - DERP_HTTP_PORT=80  # HTTP port (for certificate validation)
11
      - DERP_STUN_PORT=3478  # STUN port
12
      - DERP_DOMAIN=derper.example.com  # Replace with your domain
13
      - DERP_VERIFY_CLIENTS=true  # Enable client verification
14
    ports:
15
      - "443:443"
16
      - "80:80"
17
      - "3478:3478/udp"
18
    volumes:
19
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
20
      - ./certs:/app/certs

Environment Variables#

Variable	Required	Description	Default
`DERP_DOMAIN`	Yes	DERP server domain name	`your-hostname.com`
`DERP_CERT_DIR`	No	Certificate storage directory	`/app/certs`
`DERP_CERT_MODE`	No	Certificate mode: `manual` or `letsencrypt` (auto)	`letsencrypt`
`DERP_ADDR`	No	DERP service listen address	`:443`
`DERP_STUN`	No	Enable STUN service	`true`
`DERP_STUN_PORT`	No	STUN service port	`3478`
`DERP_HTTP_PORT`	No	HTTP service port, set to `-1` to disable	`80`
`DERP_VERIFY_CLIENTS`	No	Verify client identity via local Tailscale client	`false`

Using Custom Ports#

If your server’s ports 80/443 are already in use, you can use custom ports:

1
version: '3.8'
2
services:
3
  derper:
4
    image: fredliang/derper
5
    container_name: derper
6
    restart: always
7
    environment:
8
      - DERP_CERT_MODE=manual
9
      - DERP_ADDR=:13477  # Custom DERP port
10
      - DERP_HTTP_PORT=13476  # Custom HTTP port
11
      - DERP_STUN_PORT=13478  # Custom STUN port
12
      - DERP_DOMAIN=derper.example.com
13
      - DERP_VERIFY_CLIENTS=true
14
    ports:
15
      - "13477:13477"
16
      - "13476:13476"
17
      - "13478:13478/udp"
18
    volumes:
19
      - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock
20
      - ./certs:/app/certs

NOTE
When using custom ports, you’ll need to modify DERPPort and STUNPort in the Tailscale ACL configuration accordingly.

Method 2: Manual Compilation#

If you want a deeper understanding of how Derper works, or need custom compilation, choose the manual compilation method.

Install Golang#

Derper is written in Go, so you need to install Golang first (version 1.21 or higher recommended):

1
# Download Golang (1.22.0 example)
2
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
3

4
# Extract to /usr/local
5
sudo rm -rf /usr/local/go
6
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
7

8
# Configure environment variables
9
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
10
source ~/.bashrc
11

12
# Verify installation
13
go version

Compile Derper#

1
# Clone Tailscale repository
2
git clone https://github.com/tailscale/tailscale.git
3
cd tailscale
4

5
# Compile derper
6
go build cmd/derper/derper.go
7

8
# Move to system path
9
sudo mv derper /usr/sbin/derper

Create Systemd Service#

Create service file /etc/systemd/system/derper.service:

1
[Unit]
2
Description=Tailscale Derper
3
Wants=network-pre.target
4
After=network-pre.target NetworkManager.service systemd-resolved.service
5

6
[Service]
7
ExecStart=/usr/sbin/derper \
8
  --hostname=derper.example.com \
9
  -a :443 \
10
  -http-port 80 \
11
  -certmode letsencrypt \
12
  --certdir /var/lib/derper/certs \
13
  -verify-clients
14
Restart=on-failure
15
RestartSec=5
16

17
[Install]
18
WantedBy=multi-user.target

Parameter explanation:

--hostname: Your domain name
-a: DERP service listen address
-http-port: HTTP port for Let’s Encrypt certificate validation
-certmode: Certificate mode, letsencrypt for auto, manual for manual management
--certdir: Certificate storage directory
-verify-clients: Enable client verification (prevents unauthorized usage)

Start Service#

1
# Create certificate directory
2
sudo mkdir -p /var/lib/derper/certs
3

4
# Reload systemd configuration
5
sudo systemctl daemon-reload
6

7
# Start and enable auto-start
8
sudo systemctl enable derper
9
sudo systemctl start derper
10

11
# Check service status
12
sudo systemctl status derper

Certificate Management#

Automatic Certificate (Let’s Encrypt)#

If using standard ports 80/443, Derper can automatically request and renew Let’s Encrypt certificates:

Docker method:

1
environment:
2
  - DERP_CERT_MODE=letsencrypt
3
  - DERP_ADDR=:443
4
  - DERP_HTTP_PORT=80

Manual compilation method:

1
ExecStart=/usr/sbin/derper \
2
  --hostname=derper.example.com \
3
  -a :443 \
4
  -http-port 80 \
5
  -certmode letsencrypt \
6
  --certdir /var/lib/derper/certs

Manual Certificate Management#

If using custom ports or existing certificates, you need to manage certificates manually.

Certificate file naming convention:

domain.crt (full certificate chain)
domain.key (private key)

Example: derper.example.com.crt and derper.example.com.key

Place certificates in:

Docker: ./certs/ directory (same level as docker-compose.yml)
Manual compilation: /var/lib/derper/certs/ directory

Client Verification#

To prevent unauthorized usage of your self-hosted Derper server, it’s highly recommended to enable client verification. When enabled, only devices in your Tailscale network can use this Derper server.

Install Tailscale Client#

Install Tailscale client on the Derper server:

1
# Install Tailscale
2
curl -fsSL https://tailscale.com/install.sh | sh
3

4
# Start and join network
5
sudo tailscale up

Enable Verification#

Docker method:

Ensure docker-compose.yml includes:

1
environment:
2
  - DERP_VERIFY_CLIENTS=true
3
volumes:
4
  - /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock

Manual compilation method:

Add -verify-clients parameter in systemd service file:

1
ExecStart=/usr/sbin/derper \
2
  --hostname=derper.example.com \
3
  -a :443 \
4
  -http-port 80 \
5
  -certmode letsencrypt \
6
  --certdir /var/lib/derper/certs \
7
  -verify-clients

Restart service:

1
sudo systemctl daemon-reload
2
sudo systemctl restart derper

Configure Tailscale#

Modify Access Controls#

Visit Tailscale Admin Console
Add custom DERP configuration in Access Controls

Add at the end of configuration file (keep other configurations):

1
{
2
  // ... other configurations ...
3

4
  "derpMap": {
5
    "OmitDefaultRegions": false,  // Keep official servers as backup
6
    "Regions": {
7
      "900": {
8
        "RegionID": 900,
9
        "RegionCode": "myderp",
10
        "RegionName": "My Custom Derper",
11
        "Nodes": [
12
          {
13
            "Name": "1",
14
            "RegionID": 900,
15
            "HostName": "derper.example.com",  // Your domain
16
            "DERPPort": 443,  // Modify if using custom port
17
            "STUNPort": 3478,  // Modify if using custom port
18
            "STUNOnly": false
19
          }
20
        ]
21
      }
22
    }
23
  }
24
}

Configuration explanation:

RegionID: Custom ID, recommended 900+ to avoid conflicts with official servers
RegionCode: Region code, customizable
RegionName: Display name, can use any language
HostName: Derper server domain
DERPPort: DERP service port (default 443)
STUNPort: STUN service port (default 3478)
OmitDefaultRegions: Whether to disable official servers (recommended to keep as backup)

Disable Official DERP Servers (Optional)#

If you want to use only your self-hosted server, you can disable official DERPs:

1
{
2
  "derpMap": {
3
    "OmitDefaultRegions": false,
4
    "Regions": {
5
      "900": {
6
        // ... your custom server configuration ...
7
      },
8
      // Disable specific official servers
9
      "1": null,
10
      "2": null,
11
      "3": null,
12
      // ... other IDs ...
13
      // Recommended to keep one as backup
14
      // "20": null,  # Hong Kong, as backup
15
    }
16
  }
17
}

WARNING
Not recommended to completely disable all official servers, in case your self-hosted server fails and Tailscale becomes completely unavailable.

Testing and Verification#

After configuration, test on any Tailscale-connected client:

Check Network Status#

1
tailscale netcheck

You should see output similar to:

1
Report:
2
        * Time: 2025-12-30T02:39:55.29863832Z
3
        * UDP: true
4
        * IPv4: yes, ip:port
5
        * IPv6: no, but OS has support
6
        * MappingVariesByDestIP: false
7
        * PortMapping:
8
        * CaptivePortal: false
9
        * Nearest DERP: catcat-derp
10
        * DERP latency:
11
                -  sa: 43.2ms  (catcat-derp)
12
                - lax: 155.9ms (Los Angeles)
13
                - sea: 165.5ms (Seattle)
14
                - den: 169.7ms (Denver)
15
                - sfo: 172.9ms (San Francisco)
16
                - nue: 173.2ms (Nuremberg)
17
                - dfw: 177.9ms (Dallas)
18
                - hel: 182.8ms (Helsinki)
19
                - hkg: 184.2ms (Hong Kong)
20
                - hnl: 192.1ms (Honolulu)
21
                - iad: 194.7ms (Ashburn)
22
                - tor: 203.8ms (Toronto)
23
                - ord: 206.5ms (Chicago)
24
                - nyc: 207.6ms (New York City)
25
                - mia: 216.1ms (Miami)
26
                - tok: 216.2ms (Tokyo)
27
                - par: 220.2ms (Paris)
28
                - fra: 220.7ms (Frankfurt)
29
                - lhr: 225.3ms (London)
30
                - ams: 231.4ms (Amsterdam)
31
                - waw: 237.6ms (Warsaw)
32
                - mad: 238.4ms (Madrid)
33
                - sin: 248.2ms (Singapore)
34
                - syd: 291.3ms (Sydney)
35
                - sao: 335.8ms (São Paulo)
36
                - dbi: 340ms   (Dubai)
37
                - blr: 344.4ms (Bangalore)
38
                - nai: 359.3ms (Nairobi)
39
                - jnb: 385.1ms (Johannesburg)

Nearest DERP showing your self-hosted server name indicates successful configuration.

Test Connection Latency#

1
tailscale ping <device-name-or-ip>
2
tailscale netcheck

1
Report:
2
        * Time: 2025-12-30T02:39:55.29863832Z
3
        * UDP: true
4
        * IPv4: yes, ip:port
5
        * IPv6: no, but OS has support
6
        * MappingVariesByDestIP: false
7
        * PortMapping:
8
        * CaptivePortal: false
9
        * Nearest DERP: catcat-derp
10
        * DERP latency:
11
                -  sa: 43.2ms  (catcat-derp)
12
                - lax: 155.9ms (Los Angeles)
13
                - sea: 165.5ms (Seattle)
14
                - den: 169.7ms (Denver)
15
                - sfo: 172.9ms (San Francisco)
16
                - nue: 173.2ms (Nuremberg)
17
                - dfw: 177.9ms (Dallas)
18
                - hel: 182.8ms (Helsinki)
19
                - hkg: 184.2ms (Hong Kong)
20
                - hnl: 192.1ms (Honolulu)
21
                - iad: 194.7ms (Ashburn)
22
                - tor: 203.8ms (Toronto)
23
                - ord: 206.5ms (Chicago)
24
                - nyc: 207.6ms (New York City)
25
                - mia: 216.1ms (Miami)
26
                - tok: 216.2ms (Tokyo)
27
                - par: 220.2ms (Paris)
28
                - fra: 220.7ms (Frankfurt)
29
                - lhr: 225.3ms (London)
30
                - ams: 231.4ms (Amsterdam)
31
                - waw: 237.6ms (Warsaw)
32
                - mad: 238.4ms (Madrid)
33
                - sin: 248.2ms (Singapore)
34
                - syd: 291.3ms (Sydney)
35
                - sao: 335.8ms (São Paulo)
36
                - dbi: 340ms   (Dubai)
37
                - blr: 344.4ms (Bangalore)
38
                - nai: 359.3ms (Nairobi)
39
                - jnb: 385.1ms (Johannesburg)

Look for your custom DERP server name (e.g., catcat-derp, depending on your naming) appearing at the top with the lowest latency, indicating traffic is relaying through your self-hosted Derper.

Check Server Logs#

Docker method:

1
docker logs -f derper

Manual compilation method:

1
sudo journalctl -u derper -f

Successful connection logs look like:

1
derper: accepting connection from 100.64.1.2:41234
2
derper: serving client 100.64.1.2

Troubleshooting#

1. Certificate Validation Failure#

Problem: Let’s Encrypt certificate request failed

Solutions:

Confirm domain is correctly resolved to server IP
Confirm firewall has opened port 80
Check if other services are using port 80
Review service logs for specific errors

2. Client Cannot Connect#

Problem: tailscale netcheck doesn’t show self-hosted server

Solutions:

Confirm Tailscale ACL configuration is saved
Wait a few minutes for configuration to take effect
Restart client Tailscale service
Check server firewall has correctly opened ports

3. DERP Verification Failure#

Problem: Cannot connect after enabling verify-clients

Solutions:

Confirm Tailscale client on server is started and joined network
Check if /var/run/tailscale/tailscaled.sock exists
For Docker, confirm socket file is correctly mounted
Review logs to confirm verification process

4. Cannot Connect After Using Custom Ports#

Problem: Service unavailable after modifying ports

Solutions:

Confirm firewall has opened corresponding ports
Confirm DERPPort and STUNPort in ACL are modified accordingly
Use telnet or nc to test port connectivity

Conclusion#

By self-hosting a Tailscale Derper server, you can effectively reduce relay latency and improve network experience. Docker deployment is simple and fast, suitable for quick setup; manual compilation offers more flexibility and control.

For production environments, it’s recommended to enable client verification and automatic certificate renewal to ensure service security and stability. Also, keep some official DERP servers as backup to avoid single point of failure causing network unavailability.