Tailscale Sidecar Deployment

When to Use This Skill

Activate when:

• •User requests "deploy to production", "set up Tailscale"
• •Need to create Docker deployment configuration
• •Setting up private networking for F# application
• •Deploying to Portainer or home server
• •User mentions "docker-compose", "deployment", or "Tailscale"

Prerequisites

• •Docker and Docker Compose installed
• •Tailscale account (https://tailscale.com)
• •F# application with Dockerfile (multi-stage build)
• •Target deployment server (Linux recommended)

Architecture

Internet
    ↓ (blocked - no public ports)
Tailscale Network (WireGuard encrypted)
    ↓
Tailscale Sidecar Container
    ↓ (internal network)
F# Application Container

Key Benefits:

• •No public ports exposed
• •No authentication needed (Tailscale handles it)
• •Access from any device on your Tailnet
• •Encrypted WireGuard connections
• •Device authorization at network level

docker-compose.yml

Location: Project root

version: '3.8'

services:
  # F# Application
  app:
    build: .
    container_name: my-fsharp-app
    restart: unless-stopped
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:5000
    volumes:
      # Persist SQLite database and files
      - ./data:/app/data
    networks:
      - app-network
    depends_on:
      - tailscale
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

  # Tailscale Sidecar
  tailscale:
    image: tailscale/tailscale:latest
    container_name: my-fsharp-app-tailscale
    hostname: my-fsharp-app
    restart: unless-stopped
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_HOSTNAME=my-fsharp-app
      - TS_ACCEPT_DNS=true
      - TS_USERSPACE=false
    volumes:
      - tailscale-data:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "tailscale", "status"]
      interval: 30s
      timeout: 5s
      retries: 3

networks:
  app-network:
    driver: bridge

volumes:
  tailscale-data:

Configuration Notes:

• •hostname - Name that appears in Tailscale admin console
• •TS_HOSTNAME - DNS name on Tailnet (access via http://my-fsharp-app)
• •TS_AUTHKEY - One-time auth key from Tailscale admin
• •/dev/net/tun - Required for Tailscale networking
• •cap_add - Required Linux capabilities for VPN

Environment Configuration

.env File

Location: Project root (same directory as docker-compose.yml)

# Tailscale authentication key
TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxx

# Application settings (optional)
ASPNETCORE_ENVIRONMENT=Production

Important:

• •Add .env to .gitignore (never commit secrets)
• •Auth key is one-time use
• •Generate new key for each deployment

Generate Tailscale Auth Key

1. •Go to https://login.tailscale.com/admin/settings/keys
2. •Click "Generate auth key"
3. •Settings:
   • •✅ Reusable (if deploying multiple times)
   • •✅ Ephemeral (device removed when container stops)
   • •Set expiration (recommend 90 days)
4. •Copy key to .env file

Deployment Steps

Local Development Testing

# 1. Build application
dotnet build

# 2. Build Docker image
docker build -t my-fsharp-app:latest .

# 3. Start stack
docker-compose up -d

# 4. Check logs
docker-compose logs -f

# 5. Verify Tailscale connection
docker exec my-fsharp-app-tailscale tailscale status

# 6. Access application
# Open browser: http://my-fsharp-app (from any device on Tailnet)

Production Deployment (Portainer)

Option 1: Using Portainer UI

1. •Login to Portainer (usually http://server:9000)
2. •Go to Stacks → Add stack
3. •Name: my-fsharp-app
4. •Build method: Web editor
5. •Paste docker-compose.yml content
6. •Environment variables:
   • •Add: TS_AUTHKEY = tskey-auth-xxxxx
7. •Click Deploy the stack

Option 2: Using Git Repository

1. •Push docker-compose.yml to Git repository
2. •In Portainer: Stacks → Add stack
3. •Build method: Repository
4. •Enter Git URL and branch
5. •Set environment variables
6. •Enable Automatic updates (optional)
7. •Click Deploy the stack

Verify Deployment

# Check container status
docker ps

# Check app logs
docker logs my-fsharp-app

# Check Tailscale logs
docker logs my-fsharp-app-tailscale

# Verify Tailscale connection
docker exec my-fsharp-app-tailscale tailscale status

# Check health
docker inspect my-fsharp-app | grep -A 5 Health

# Test app endpoint
curl http://localhost:5000/health  # From server
curl http://my-fsharp-app/health    # From Tailnet device

Accessing the Application

From Tailnet Devices

Any device on your Tailnet can access:

http://my-fsharp-app
http://my-fsharp-app:5000

Install Tailscale on devices:

• •Desktop: https://tailscale.com/download
• •Mobile: App Store / Google Play
• •Login with same Tailscale account

From Server (Local)

# Use localhost
curl http://localhost:5000

# Or use Tailscale hostname
curl http://my-fsharp-app:5000

Updating the Application

Update Code and Redeploy

# 1. Pull latest code
git pull origin main

# 2. Rebuild Docker image
docker-compose build

# 3. Restart containers
docker-compose up -d

# 4. Check logs
docker-compose logs -f app

In Portainer

1. •Go to Stacks → your stack
2. •Click Editor
3. •Click Update the stack
4. •Select Re-pull image and redeploy
5. •Click Update

Troubleshooting

Tailscale Connection Issues

# Check Tailscale status
docker exec my-fsharp-app-tailscale tailscale status

# Check Tailscale logs
docker logs my-fsharp-app-tailscale

# Verify /dev/net/tun exists
ls -la /dev/net/tun

# Restart Tailscale container
docker restart my-fsharp-app-tailscale

# Check network capabilities
docker exec my-fsharp-app-tailscale ip addr show

Common Issues:

Application Issues

# Check app is running
docker ps | grep my-fsharp-app

# Check app logs
docker logs my-fsharp-app --tail 100

# Check app health
docker exec my-fsharp-app curl -f http://localhost:5000/health

# Check data volume
docker exec my-fsharp-app ls -la /app/data

# Restart app
docker restart my-fsharp-app

Network Issues

# Check network exists
docker network ls | grep app-network

# Inspect network
docker network inspect app-network

# Check containers can communicate
docker exec my-fsharp-app-tailscale ping -c 3 my-fsharp-app

Data Persistence Issues

# Check volume exists
docker volume ls | grep tailscale

# Check data directory
ls -la ./data

# Fix permissions (if needed)
sudo chown -R $(id -u):$(id -g) ./data

Multiple Applications

Deploy multiple F# apps on same server:

# app1/docker-compose.yml
services:
  app:
    container_name: todo-app
    # ... config
  tailscale:
    container_name: todo-app-tailscale
    hostname: todo-app
    environment:
      - TS_HOSTNAME=todo-app
    # ... config

# app2/docker-compose.yml
services:
  app:
    container_name: notes-app
    # ... config
  tailscale:
    container_name: notes-app-tailscale
    hostname: notes-app
    environment:
      - TS_HOSTNAME=notes-app
    # ... config

Access:

• •http://todo-app
• •http://notes-app

Best Practices

✅ Do

• •Use unique hostnames for each application
• •Set auth key expiration (security)
• •Use ephemeral keys for temporary deployments
• •Monitor Tailscale connection health
• •Keep Tailscale image updated
• •Persist data in volumes (not containers)
• •Use health checks
• •Test locally before production deployment

❌ Don't

• •Expose ports to public internet (defeats Tailscale purpose)
• •Commit .env file to Git
• •Reuse auth keys across environments
• •Run without NET_ADMIN capability
• •Forget to mount /dev/net/tun
• •Skip health checks
• •Deploy without testing locally first

Security Considerations

Tailscale Provides:

• •Network-level authentication (device authorization)
• •WireGuard encryption
• •Access control via Tailscale ACLs
• •Automatic certificate management

Application Still Needs:

• •Input validation (SQL injection, XSS prevention)
• •Authorization (who can do what in the app)
• •Secure data storage
• •Audit logging

Tailscale Admin:

• •Review connected devices regularly
• •Disable/remove unused devices
• •Use ACLs to restrict access by group
• •Enable MFA for Tailscale account

Verification Checklist

• • docker-compose.yml created
• • .env file created with TS_AUTHKEY
• • .env added to .gitignore
• • Tailscale auth key generated
• • Application Dockerfile exists
• • Data directory created
• • Containers start successfully
• • Tailscale shows connected
• • Application accessible via Tailscale hostname
• • Health checks passing
• • Logs show no errors

Related Skills

• •fsharp-feature - Complete application to deploy
• •fsharp-backend - Backend that gets deployed
• •fsharp-frontend - Frontend that gets deployed

Related Documentation

• •/docs/07-BUILD-DEPLOY.md - Docker build and deployment guide
• •/docs/08-TAILSCALE-INTEGRATION.md - Detailed Tailscale integration
• •CLAUDE.md - Deployment model overview

Additional Resources

• •Tailscale Documentation
• •Docker Compose Documentation
• •Portainer Documentation
• •ASP.NET Core Deployment