Sanitized mirror from private repository - 2026-04-06 02:25:47 UTC

2026-04-06 02:25:48 +00:00
commit fad8c41112
1407 changed files with 358727 additions and 0 deletions
--- a/docs/infrastructure/tailscale-setup-guide.md
+++ b/docs/infrastructure/tailscale-setup-guide.md
@@ -0,0 +1,528 @@
+# 🌐 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!