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:

```rust
// 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:

```bash
# 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:

```bash
# 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:

```bash
# 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