docker.recipes

Tailscale VPN

beginner

Tailscale mesh VPN for secure access to your services.

Overview

Tailscale is a modern VPN service built on WireGuard that creates secure mesh networks between devices without complex configuration or centralized servers. Founded in 2019 by former Google engineers, Tailscale eliminates the traditional hub-and-spoke VPN model by establishing direct encrypted connections between devices, using a coordination server only for initial handshakes and key exchange. The service automatically handles NAT traversal, provides zero-configuration networking, and integrates with identity providers for authentication. This Docker deployment of Tailscale transforms your container host into a mesh network node that can securely connect to other devices in your Tailscale network while providing subnet routing capabilities for your local Docker networks. The containerized approach allows you to manage VPN connectivity as part of your infrastructure-as-code workflow, with the container acting as a gateway that can advertise Docker networks to your broader Tailscale mesh. This configuration is particularly valuable for organizations implementing zero-trust networking principles, remote development teams needing secure access to containerized applications, and homelab enthusiasts who want to access their Docker services from anywhere without exposing ports to the internet.

Key Features

  • WireGuard-based mesh networking with automatic peer discovery and connection establishment
  • MagicDNS integration providing automatic hostname resolution across the mesh network
  • Subnet routing capabilities to advertise Docker networks to other Tailscale nodes
  • Exit node functionality allowing traffic routing through the Docker host
  • Access Control Lists (ACLs) for fine-grained network security policies
  • Automatic NAT traversal and firewall hole punching for direct connections
  • Integration with identity providers including Google, Microsoft, and GitHub
  • Container tagging support for policy-based access control

Common Use Cases

  • 1Remote development teams accessing containerized applications without exposing public ports
  • 2Homelab enthusiasts creating secure access to self-hosted services from anywhere
  • 3Organizations implementing zero-trust network architecture for container workloads
  • 4Multi-cloud deployments requiring secure inter-site communication between Docker environments
  • 5Development and staging environments needing isolated but accessible testing infrastructure
  • 6Site-to-site connectivity for distributed Docker Swarm or Kubernetes clusters
  • 7Secure CI/CD pipelines accessing private container registries and deployment targets

Prerequisites

  • Tailscale account with admin access to generate authentication keys
  • Docker host with NET_ADMIN and SYS_MODULE capabilities support
  • Minimum 512MB RAM allocation for the Tailscale container
  • /dev/net/tun device availability on the host system
  • Understanding of your network topology for subnet routing configuration
  • Familiarity with Tailscale ACL syntax if implementing custom access policies

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  tailscale: 
3    image: tailscale/tailscale:latest
4    container_name: tailscale
5    hostname: docker-tailscale
6    environment: 
7      - TS_AUTHKEY=${TS_AUTHKEY}
8      - TS_EXTRA_ARGS=--advertise-tags=tag:container
9      - TS_STATE_DIR=/var/lib/tailscale
10      - TS_USERSPACE=false
11    volumes: 
12      - tailscale_data:/var/lib/tailscale
13      - /dev/net/tun:/dev/net/tun
14    cap_add: 
15      - NET_ADMIN
16      - SYS_MODULE
17    restart: unless-stopped
18    networks: 
19      - tailscale-network
20
21volumes: 
22  tailscale_data: 
23
24networks: 
25  tailscale-network: 
26    driver: bridge

.env Template

.env
1# Tailscale
2TS_AUTHKEY=tskey-auth-xxxx-xxxxxxxxxxxx

Usage Notes

  1. 1Generate auth key at tailscale.com/admin
  2. 2Enable subnet routing for LAN access
  3. 3Use as exit node
  4. 4MagicDNS for hostnames
  5. 5Access Control Lists for security

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  tailscale:
5    image: tailscale/tailscale:latest
6    container_name: tailscale
7    hostname: docker-tailscale
8    environment:
9      - TS_AUTHKEY=${TS_AUTHKEY}
10      - TS_EXTRA_ARGS=--advertise-tags=tag:container
11      - TS_STATE_DIR=/var/lib/tailscale
12      - TS_USERSPACE=false
13    volumes:
14      - tailscale_data:/var/lib/tailscale
15      - /dev/net/tun:/dev/net/tun
16    cap_add:
17      - NET_ADMIN
18      - SYS_MODULE
19    restart: unless-stopped
20    networks:
21      - tailscale-network
22
23volumes:
24  tailscale_data:
25
26networks:
27  tailscale-network:
28    driver: bridge
29EOF
30
31# 2. Create the .env file
32cat > .env << 'EOF'
33# Tailscale
34TS_AUTHKEY=tskey-auth-xxxx-xxxxxxxxxxxx
35EOF
36
37# 3. Start the services
38docker compose up -d
39
40# 4. View logs
41docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/tailscale-vpn/run | bash

Troubleshooting

  • Container fails with 'cannot open TUN device': Ensure /dev/net/tun exists and container has NET_ADMIN capability
  • Authentication fails on startup: Verify TS_AUTHKEY is valid and not expired in Tailscale admin console
  • Other nodes cannot reach advertised subnets: Enable IP forwarding on Docker host and approve subnet routes in Tailscale admin
  • Container restarts continuously: Check if another Tailscale instance is running on the same machine with conflicting state
  • MagicDNS not resolving container hostnames: Ensure MagicDNS is enabled in Tailscale settings and hostname is properly set
  • Exit node traffic not routing: Verify TS_EXTRA_ARGS includes --advertise-exit-node and approve exit node in admin console

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

tailscale

Tags

#tailscale#vpn#wireguard#mesh-network#zero-trust

Category

Security & Networking

Related Recipes

Ad Space