archy/docs/TAILSCALE-INTEGRATION.md

Tailscale Integration Guide

Overview

Archipelago integrates with Tailscale to provide secure remote access via your personal VPN mesh network. When Tailscale is installed, users can access their Archipelago UI from anywhere using their Tailscale network.

Automatic Configuration

Installation Process

When a user installs Tailscale from the Archipelago App Store:

1. Container Setup (automatic)

   • Tailscale container runs with --network=host and --privileged mode
   • Creates /var/lib/archipelago/tailscale for persistent state
   • Starts Tailscale daemon and web UI on port 8240

2. User Authentication (user action required)

   • User clicks "Launch" on Tailscale app
   • Opens web UI at http://<local-ip>:8240
   • User logs in with their Tailscale account
   • Device registers to their tailnet

3. Network Configuration (automatic)

   • tailscale0 interface is created with Tailscale IP (e.g., 100.91.10.103)
   • Nginx detects the new interface and adds it to listen directives
   • Archipelago UI becomes accessible via Tailscale hostname

Accessing via Tailscale

After setup, users can access Archipelago from any device on their tailnet:

http://<hostname>.tail<xxxxxx>.ts.net/

Example: http://archipelago.tail2b6225.ts.net/

Technical Implementation

Container Configuration

Tailscale requires special container permissions:

// In rpc.rs - handle_package_install()
if package_id == "tailscale" {
    run_args.push("--network=host");      // Access host network
    run_args.push("--privileged");        // Full container capabilities
    run_args.push("--cap-add=NET_ADMIN"); // Network administration
    run_args.push("--cap-add=NET_RAW");   // Raw packet access
    run_args.push("--device=/dev/net/tun"); // TUN device for VPN
}

Nginx Configuration

The configure-tailscale-nginx.sh script automatically:

1. Detects the Tailscale IP from tailscale0 interface
2. Adds listen <tailscale-ip>:80; to Nginx config
3. Reloads Nginx to accept connections from tailnet

Post-Installation Automation

A systemd service (archipelago-tailscale.service) runs after Archipelago starts:

• Waits for tailscale0 interface to exist
• Runs configuration script
• Ensures Nginx is ready for tailnet connections

User Experience Flow

First-Time Setup

1. User installs Tailscale from App Store

   • Container downloads and starts
   • "Launch" button appears in My Apps

2. User authenticates

   • Clicks "Launch" → opens web UI
   • Logs in with Tailscale account
   • Approves device in Tailscale admin console

3. Automatic configuration

   • System detects Tailscale connection
   • Nginx reconfigures automatically
   • User receives tailnet hostname

4. Remote access enabled

   • User can now access from anywhere
   • All devices on their tailnet can connect
   • Uses Tailscale's encrypted mesh network

Ongoing Usage

• No maintenance required - Tailscale auto-starts with system
• Automatic reconnection - Container restart policy handles disconnects
• Persistent state - Authentication survives reboots
• Web UI always available - Manage Tailscale at port 8240

Security Considerations

Why Privileged Mode?

Tailscale requires privileged mode because it:

• Creates a TUN device for VPN traffic
• Modifies iptables rules for routing
• Manages network interfaces on the host

Network Isolation

• Tailscale runs in host network mode (no container network isolation)
• Only users on the same tailnet can access the Archipelago UI
• Tailscale provides authentication and encryption

Data Persistence

• Tailscale state is stored in /var/lib/archipelago/tailscale/
• Contains device identity and credentials
• Persists across container recreations
• Automatically backed up with system

Troubleshooting

Tailscale UI Not Loading

If the web UI doesn't load:

# Check container status
sudo podman ps --filter name=tailscale

# Check logs
sudo podman logs tailscale

# Verify interface
ip addr show tailscale0

# Check Nginx configuration
sudo nginx -t
sudo systemctl status nginx

Remote Access Not Working

If Tailscale hostname doesn't resolve:

# Check Tailscale status
sudo podman exec tailscale tailscale status

# Verify Nginx is listening on Tailscale IP
sudo netstat -tlnp | grep :80

# Re-run configuration script
sudo /opt/archipelago/scripts/configure-tailscale-nginx.sh

Container Won't Start

If container fails to start:

# Check for permission issues
sudo dmesg | grep -i deny

# Verify TUN device exists
ls -l /dev/net/tun

# Check SELinux/AppArmor
sudo ausearch -m avc -ts recent  # SELinux
sudo dmesg | grep -i apparmor    # AppArmor

Future Enhancements

• Automatic hostname detection - Display tailnet URL in UI
• MagicDNS support - Use short hostnames (just archipelago)
• Subnet routing - Route to other networks via Archipelago
• Exit node mode - Use Archipelago as internet gateway
• ACL integration - Fine-grained access control via Tailscale ACLs