homelab-optimized/docs/infrastructure/tailscale-setup-guide.md

# 🌐 Tailscale Setup Guide with Split-Brain DNS

**🟡 Intermediate Guide**

This guide shows you how to set up Tailscale for secure homelab access with split-brain DNS, allowing you to use local hostnames like `atlantis.vish.local` from anywhere in the world.

## 🎯 Why Tailscale Over Traditional VPN?

### ✅ **Advantages of Tailscale**
- **Zero-config mesh networking** - No complex server setup
- **NAT traversal** - Works behind any router/firewall
- **Split-brain DNS** - Use local hostnames anywhere
- **Per-device access control** - Granular permissions
- **Cross-platform** - Works on everything
- **No port forwarding needed** - Completely eliminates router configuration

### 🆚 **Tailscale vs WireGuard**
| Feature | Tailscale | Traditional WireGuard |
|---------|-----------|----------------------|
| Setup Complexity | 🟢 Simple | 🟡 Moderate |
| NAT Traversal | 🟢 Automatic | 🔴 Manual |
| DNS Resolution | 🟢 Built-in | 🟡 Manual setup |
| Device Management | 🟢 Web dashboard | 🔴 Config files |
| Port Forwarding | 🟢 Not needed | 🔴 Required |

## 🏗️ Your Homelab Hosts

Here are all the hosts that will be accessible via Tailscale:

### 🖥️ **Primary Infrastructure**
| Hostname | IP Range | Role | Key Services |
|----------|----------|------|--------------|
| `atlantis.vish.local` | 192.168.1.x | Primary NAS | Plex, Vaultwarden, Grafana, GitLab |
| `calypso.vish.local` | 192.168.1.x | Media NAS | Immich, Arr Suite, Prometheus |
| `concord-nuc.vish.local` | 192.168.1.x | Edge Computing | Home Assistant, WireGuard, Invidious |

### 🖥️ **Virtual Machines**
| Hostname | IP Range | Role | Key Services |
|----------|----------|------|--------------|
| `homelab-vm.vish.local` | 192.168.1.x | General VM | Satisfactory, Mattermost, Signal API |
| `chicago-vm.vish.local` | 192.168.1.x | Gaming VM | Jellyfin, Factorio, Neko |
| `bulgaria-vm.vish.local` | 192.168.1.x | Utility VM | Navidrome, Droppy, Syncthing |

### 🔧 **Specialized Hosts**
| Hostname | IP Range | Role | Key Services |
|----------|----------|------|--------------|
| `anubis.vish.local` | 192.168.1.x | Archive/Backup | ArchiveBox, PhotoPrism, Matrix Conduit |
| `guava.vish.local` | 192.168.1.x | Remote Server | Ollama, CoCalc, OpenWebUI |
| `setillo.vish.local` | 192.168.1.x | Monitoring | Prometheus, AdGuard |

### 🍓 **Raspberry Pi Cluster**
| Hostname | IP Range | Role | Key Services |
|----------|----------|------|--------------|
| `rpi-vish.vish.local` | 192.168.1.x | IoT Hub | Immich, DNS Updater |
| `rpi-kevin.vish.local` | 192.168.1.x | Game Server | Minecraft, PMC |

### 🎮 **Edge Devices**
| Hostname | IP Range | Role | Key Services |
|----------|----------|------|--------------|
| `nvidia-shield.vish.local` | 192.168.1.x | Media Client | WireGuard Client |
| `contabo-vm.vish.local` | External | Cloud VM | Ollama, External Services |

## 🚀 Quick Setup (5 Minutes)

### 1. **Create Tailscale Account**
```bash
# Visit https://tailscale.com and create account
# Choose the free plan (up to 20 devices, 3 users)
```

### 2. **Install on Each Host**

#### **Ubuntu/Debian (Most VMs)**
```bash
# Add Tailscale repository
curl -fsSL https://tailscale.com/install.sh | sh

# Start Tailscale
sudo tailscale up

# Follow the authentication URL
```

#### **Synology NAS (Atlantis, Calypso)**
```bash
# Method 1: Package Center
# Search for "Tailscale" and install

# Method 2: Docker (if package not available)
docker run -d \
  --name=tailscale \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  --device=/dev/net/tun \
  -v /var/lib/tailscale:/var/lib/tailscale \
  -v /dev/net/tun:/dev/net/tun \
  tailscale/tailscale:latest \
  tailscaled
```

#### **Raspberry Pi**
```bash
# Same as Ubuntu/Debian
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
```

### 3. **Install on Client Devices**
- **Windows/Mac**: Download from https://tailscale.com/download
- **iOS/Android**: Install from app store
- **Linux Desktop**: Same as server installation

## 🌐 Split-Brain DNS Configuration

### **Current Production Configuration**
Based on your live Tailscale setup, here's your working DNS configuration:

#### **Tailnet DNS Name**: `tail.vish.gg`
- Unique identifier for your Tailscale network
- Used for DNS entries, device sharing, and TLS certificates
- Automatically assigned by Tailscale

#### **Nameserver Configuration**:
```bash
# MagicDNS (Primary)
tail.vish.gg → 100.100.100.100

# Split DNS for Local Network
vish.local → 192.168.0.250 (Use with exit mode)

# Global Nameservers (Your Homelab DNS)
100.103.48.78  # Calypso Tailscale IP
100.72.55.21   # Concord-NUC Tailscale IP
```

#### **Search Domains**: `tail.vish.gg`
- Automatically appends to short hostnames
- Enables `atlantis` → `atlantis.tail.vish.gg` resolution

### 1. **Enable MagicDNS** ✅ **Already Configured**
```bash
# Your MagicDNS is already enabled with:
# - Tailnet domain: tail.vish.gg
# - Primary DNS: 100.100.100.100 (MagicDNS)
# - Override DNS servers: ENABLED
# - Apps control: Enabled for third-party app access
```

### 2. **Add Custom DNS Records**

In the Tailscale admin console, add these DNS records:

#### **A Records (IPv4)**
```dns
atlantis.vish.local     → 192.168.1.100  # Replace with actual IP
calypso.vish.local      → 192.168.1.101
concord-nuc.vish.local  → 192.168.1.102
homelab-vm.vish.local   → 192.168.1.103
chicago-vm.vish.local   → 192.168.1.104
bulgaria-vm.vish.local  → 192.168.1.105
anubis.vish.local       → 192.168.1.106
guava.vish.local        → 192.168.1.107
setillo.vish.local      → 192.168.1.108
rpi-vish.vish.local     → 192.168.1.109
rpi-kevin.vish.local    → 192.168.1.110
nvidia-shield.vish.local → 192.168.1.111
```

#### **CNAME Records (Aliases)**
```dns
# Service-specific aliases
plex.vish.local         → atlantis.vish.local
grafana.vish.local      → atlantis.vish.local
immich.vish.local       → calypso.vish.local
homeassistant.vish.local → concord-nuc.vish.local
jellyfin.vish.local     → chicago-vm.vish.local
```

### 3. **Alternative: Local DNS Server Method**

If you prefer more control, set up a local DNS server:

#### **Pi-hole Configuration** (on Atlantis)
```bash
# Add to Pi-hole custom DNS records
# /etc/pihole/custom.list
192.168.1.100 atlantis.vish.local
192.168.1.101 calypso.vish.local
192.168.1.102 concord-nuc.vish.local
# ... add all hosts
```

#### **Tailscale DNS Settings**
```bash
# Point Tailscale to use your Pi-hole
# In admin console: DNS → Nameservers
# Add: 192.168.1.100 (Pi-hole IP)
```

## 🔧 Advanced Configuration

### 1. **Subnet Routing** (Access entire homelab network)

On your primary router/gateway host (e.g., Atlantis):
```bash
# Enable subnet routing
sudo tailscale up --advertise-routes=192.168.1.0/24

# In Tailscale admin console:
# Go to Machines → atlantis → Route settings
# Enable the advertised route
```

### 2. **Exit Node** (Route all traffic through homelab)
```bash
# On a homelab host (e.g., Atlantis)
sudo tailscale up --advertise-exit-node

# On client devices
tailscale up --exit-node=atlantis
```

### 3. **Access Control Lists (ACLs)**

Create fine-grained access control:
```json
{
  "acls": [
    {
      "action": "accept",
      "src": ["group:family"],
      "dst": ["192.168.1.0/24:*"]
    },
    {
      "action": "accept", 
      "src": ["group:admin"],
      "dst": ["*:*"]
    }
  ],
  "groups": {
    "group:family": ["user1@example.com", "user2@example.com"],
    "group:admin": ["admin@example.com"]
  }
}
```

## 📱 Client Usage Examples

### **From Your Phone**
```bash
# Access services using local hostnames
https://atlantis.vish.local:8920  # Plex
https://grafana.vish.local:3000   # Grafana
https://immich.vish.local         # Photo management
```

### **From Laptop While Traveling**
```bash
# SSH to any host
ssh user@atlantis.vish.local
ssh user@homelab-vm.vish.local

# Access web services
curl http://atlantis.vish.local:8080
```

### **Service Discovery**
```bash
# List all Tailscale devices
tailscale status

# Ping any host
ping atlantis.vish.local
ping calypso.vish.local
```

## 🛡️ Security Best Practices

### 1. **Device Authentication**
```bash
# Require device approval
# In admin console: Settings → Device approval
# Enable "Device approval required"
```

### 2. **Key Expiry**
```bash
# Set key expiration (default 180 days)
# In admin console: Settings → Key expiry
# Recommended: 90 days for better security
```

### 3. **Disable Key Expiry for Servers**
```bash
# For always-on servers, disable expiry
sudo tailscale up --auth-key=tskey-xxx --advertise-routes=192.168.1.0/24
```

### 4. **Network Segmentation**
```bash
# Use ACLs to limit access between devices
# Example: Only allow admin devices to access management interfaces
```

## 🔍 Troubleshooting

### **DNS Not Resolving**
```bash
# Check MagicDNS status
tailscale status --json | jq '.MagicDNSSuffix'

# Test DNS resolution
nslookup atlantis.vish.local
dig atlantis.vish.local

# Force DNS refresh
sudo tailscale up --reset
```

### **Can't Access Local Services**
```bash
# Check if subnet routing is enabled
tailscale status | grep "subnet routes"

# Verify routes in admin console
# Machines → [host] → Route settings

# Test connectivity
ping 192.168.1.100
telnet atlantis.vish.local 8080
```

### **Connection Issues**
```bash
# Check Tailscale status
tailscale status

# View logs
sudo journalctl -u tailscaled -f

# Restart Tailscale
sudo systemctl restart tailscaled
```

## 📊 Service Access Map

Once configured, you can access services like this:

### **Media Services**
```bash
# Plex Media Server
https://atlantis.vish.local:32400

# Immich Photos
https://calypso.vish.local:2283

# Jellyfin
https://chicago-vm.vish.local:8096

# Navidrome Music
https://bulgaria-vm.vish.local:4533
```

### **Management & Monitoring**
```bash
# Grafana Dashboards
https://atlantis.vish.local:3000

# Prometheus Metrics
https://calypso.vish.local:9090

# Uptime Kuma
https://atlantis.vish.local:3001

# Portainer
https://atlantis.vish.local:9000
```

### **Development & Productivity**
```bash
# GitLab
https://atlantis.vish.local:8929

# Vaultwarden (Password Manager)
https://atlantis.vish.local:8222

# Home Assistant
https://concord-nuc.vish.local:8123

# Mattermost Chat
https://homelab-vm.vish.local:8065
```

## 🚀 Migration from WireGuard

If you're currently using WireGuard:

### 1. **Parallel Setup**
```bash
# Keep WireGuard running while testing Tailscale
# Both can coexist temporarily
```

### 2. **Test All Services**
```bash
# Verify each service works via Tailscale
# Test from multiple client devices
```

### 3. **Update Documentation**
```bash
# Update service URLs in documentation
# Change from external IPs to .vish.local hostnames
```

### 4. **Decommission WireGuard**
```bash
# Once confident, disable WireGuard
# Remove port forwarding rules
# Keep configs as backup
```

## 💡 Pro Tips

### **1. Use Descriptive Hostnames**
```bash
# Instead of generic names, use descriptive ones
media-server.vish.local    # Instead of atlantis.vish.local
monitoring.vish.local      # For Grafana/Prometheus host
gaming.vish.local          # For game servers
```

### **2. Create Service-Specific Aliases**
```bash
# Add CNAME records for easy access
plex.vish.local → atlantis.vish.local
photos.vish.local → calypso.vish.local
chat.vish.local → homelab-vm.vish.local
```

### **3. Mobile Shortcuts**
```bash
# Create bookmarks/shortcuts on mobile devices
# Use descriptive names: "Home Plex", "Photo Library", etc.
```

### **4. Monitoring Integration**
```bash
# Update Uptime Kuma to monitor .vish.local hostnames
# Update Grafana dashboards to use local hostnames
# Configure alerts to use Tailscale IPs
```

## 🔗 Integration with Existing Services

### **Update Service Configurations**
Many services can be updated to use Tailscale hostnames:

```yaml
# Example: Update docker-compose.yml files
environment:
  - GRAFANA_URL=https://grafana.vish.local:3000
  - PLEX_URL=https://plex.vish.local:32400
  - DATABASE_HOST=atlantis.vish.local
```

### **Reverse Proxy Updates**
```nginx
# Update Nginx Proxy Manager
# Change upstream servers to use .vish.local hostnames
upstream plex {
    server atlantis.vish.local:32400;
}
```

## 📋 Quick Reference

### **Essential Commands**
```bash
# Check status
tailscale status

# Connect/disconnect
tailscale up
tailscale down

# List devices
tailscale status --peers

# Get IP address
tailscale ip -4

# Enable/disable routes
tailscale up --advertise-routes=192.168.1.0/24
```

### **Common URLs After Setup**
```bash
# Admin interfaces
https://atlantis.vish.local:9000      # Portainer
https://atlantis.vish.local:3000      # Grafana
https://atlantis.vish.local:3001      # Uptime Kuma

# Media services  
https://atlantis.vish.local:32400     # Plex
https://calypso.vish.local:2283       # Immich
https://chicago-vm.vish.local:8096    # Jellyfin

# Communication
https://homelab-vm.vish.local:8065    # Mattermost
https://atlantis.vish.local:8080      # Signal API
```

## 🔗 Related Documentation

- [📱 Mobile Device Setup](mobile-device-setup.md) - **NEW!** iOS, Android, macOS, Linux Tailscale configuration
- [👨‍👩‍👧‍👦 Family Network Integration](family-network-integration.md) - **NEW!** Connect family's separate network via Tailscale
- [💻 Laptop Travel Setup](laptop-travel-setup.md) - Secure travel with VPN tunneling
- [Port Forwarding Guide](port-forwarding-guide.md) - Traditional VPN setup (alternative)
- [🔥 Disaster Recovery Guide](../troubleshooting/disaster-recovery.md) - Router failure and network reconfiguration
- [🔐 Offline Password Access](../troubleshooting/offline-password-access.md) - Accessing passwords when services are down
- [Security Model](security.md) - Overall security architecture
- [Network Architecture](networking.md) - Network topology and design
- [Individual Service Docs](../services/individual/README.md) - Service-specific access information

---

**🎉 Result**: After setup, you can access your entire homelab using friendly hostnames like `atlantis.vish.local` from anywhere in the world, without any port forwarding or complex VPN configuration!