Tailscale DERP Server Docker Setup

This repository contains a Docker setup for running a custom Tailscale DERP (Designated Encrypted Relay for Packets) server. DERP servers are used by Tailscale for NAT traversal and as a fallback when direct peer-to-peer connections aren't possible.

Features

Lightweight Alpine-based container
Automatic health checking
Configurable via environment variables
Support for custom SSL certificates
STUN server functionality included
Simple deployment process

Prerequisites

Docker installed on your host system
A domain name pointed to your server
SSL certificates for your domain
Basic understanding of Tailscale networking

Quick Start

Clone this repository:

git clone https://github.com/hhftechnology/tailscale-derp-server.git
cd tailscale-derp-server

Create a certificate directory:

mkdir -p certs

Place your SSL certificates in the certs directory:

cp /path/to/your/fullchain.pem certs/cert.pem
cp /path/to/your/privkey.pem certs/key.pem

Build and run the container:

docker build -t derper .
docker run -d \
  --name derper \
  -p 10443:443/tcp \
  -p 3478:3478/udp \
  -v $(pwd)/certs:/cert \
  -e DERP_DOMAIN=your-domain.com \
  derper

Environment Variables

Variable	Description	Default
DERP_DOMAIN	Your server's hostname	your-hostname.com
DERP_VERIFY_CLIENTS	Whether to verify clients	false
DERP_CERT_DIR	Directory for certificates	/cert
DERP_PORT	Main HTTPS port	10443
DERP_STUN_PORT	STUN port	3478

Docker Compose Setup

Create a docker-compose.yml file:

version: '3.8'
services:
  derper:
    build: .
    ports:
      - "10443:443/tcp"
      - "3478:3478/udp"
    volumes:
      - ./certs:/cert
    environment:
      - DERP_DOMAIN=your-domain.com
      - DERP_VERIFY_CLIENTS=false
    restart: unless-stopped

Then run:

docker-compose up -d

SSL Certificates

The DERP server requires valid SSL certificates. You can:

Use Let's Encrypt:

certbot certonly --standalone -d your-domain.com

Copy certificates to the certs directory:

cp /etc/letsencrypt/live/your-domain.com/fullchain.pem certs/cert.pem
cp /etc/letsencrypt/live/your-domain.com/privkey.pem certs/key.pem

Configuring Tailscale to Use Your DERP Server

Create a DERP map configuration file:

{
  "Regions": {
    "901": {
      "RegionID": 901,
      "RegionCode": "custom",
      "RegionName": "Custom DERP",
      "Nodes": [
        {
          "Name": "1",
          "RegionID": 901,
          "HostName": "your-domain.com",
          "IPv4": "your-server-ip",
          "STUNPort": 3478,
          "DERPPort": 10443
        }
      ]
    }
  }
}

Configure your Tailscale network to use this DERP server (requires Tailscale Enterprise or Business plan).

Health Checking

The container includes a health check that:

Runs every 3 minutes
Times out after 30 seconds
Has a 10-second startup period
Retries 3 times before marking unhealthy
Verifies HTTPS connectivity to the DERP server

Troubleshooting

Check container logs:

docker logs derper

Verify ports are open:

netstat -tulpn | grep -E '10443|3478'

Test STUN connectivity:

stun-client your-domain.com:3478

Common issues:
- Certificate permissions
- Firewall blocking ports
- DNS resolution problems
- Certificate expiration

Security Considerations

Keep SSL certificates secure and up-to-date
Regularly update the container for security patches
Consider enabling client verification for enhanced security
Monitor logs for unusual activity
Use firewalls to restrict access if needed

Performance Tuning

For high-traffic scenarios:

Adjust Docker limits:

docker run -d \
  --ulimit nofile=65535:65535 \
  --memory=4g \
  --cpus=2 \
  ... other options ...

Tune host system:

sysctl -w net.core.rmem_max=2500000
sysctl -w net.core.wmem_max=2500000

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Submit a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Tailscale team for the DERP server implementation
Docker community for container best practices
Contributors to this project