feat(network): add Tailscale and Cloudflare Zero Trust WARP Connector

Two complementary remote-access options alongside the existing
wg-easy VPN and cloudflared tunnel.

Tailscale (services/network/tailscale/):
- Runs as a subnet router using the official tailscale/tailscale image
- Advertises your LAN subnet (TS_ROUTES) to all your Tailscale devices
- Uses kernel-mode WireGuard (NET_ADMIN + /dev/net/tun) for best perf
- host networking so it can route packets across the full LAN
- MagicDNS enabled — devices reach the server by hostname automatically
- Auth via reusable pre-authorized key (TS_AUTHKEY) — survives restarts
- No port forwarding or firewall changes required

Cloudflare Zero Trust WARP Connector (services/network/cloudflare-zero-trust/):
- Distinct from infra/cloudflared (which exposes public HTTP hostnames)
- WARP Connector gives devices running the Cloudflare WARP client
  access to private LAN IPs on any port, not just HTTP
- Same cloudflared image but configured as a private network connector
- ip_forward + NET_ADMIN enables subnet routing for WARP clients
- Comprehensive compose header explains Zero Trust setup steps,
  Split Tunneling config, and comparison with Tailscale/wg-easy

Also:
- Add missing services/infra/cloudflared/.env.example with clear
  instructions distinguishing the tunnel token from the WARP token
- Update README network table and directory tree

Co-Authored-By: Claude <noreply@anthropic.com>

Author: davidamacey

README.md

@@ -140,6 +140,8 @@ These are custom-built applications with published Docker images. They require b
 |-------------------|---------------|-----|--------------------------------------------------|
 | AdGuard Home      | 3080/5353     | -   | Network-wide DNS ad and tracker blocking         |
 | wg-easy           | 51821/51820   | -   | WireGuard VPN with a simple web UI               |
+| Tailscale         | -             | -   | Zero-config mesh VPN and subnet router (no port forwarding needed) |
+| Cloudflare Zero Trust | -         | -   | WARP Connector — private LAN access for WARP clients via Cloudflare |
 | Speedtest Tracker | 7900          | -   | Scheduled internet speed monitoring with history |
 
 ### Dev Tools (`services/dev/`)
@@ -250,6 +252,8 @@ OpenHomeLab/
 │   ├── network/
 │   │   ├── adguard-home/         # DNS ad and tracker blocking
 │   │   ├── wg-easy/              # WireGuard VPN with web UI
+│   │   ├── tailscale/            # Mesh VPN subnet router (no port forwarding)
+│   │   ├── cloudflare-zero-trust/ # WARP connector for private LAN access
 │   │   └── speedtest-tracker/    # Scheduled internet speed monitoring
 │   ├── dev/
 │   │   ├── gitea/                # Self-hosted Git service

services/infra/cloudflared/.env.example

@@ -1,10 +1,21 @@
 # ===========================================================================
-# Cloudflare Tunnel — Environment Variables
+# Cloudflare Tunnel (cloudflared) — Environment Variables
 # Copy to .env and fill in real values. .env is gitignored.
+#
+# This tunnel exposes specific homelab services to the public internet
+# via public hostnames (e.g. immich.yourdomain.com). It is the HTTP-
+# focused public access layer.
+#
+# For private network access (reach LAN IPs from your devices), see:
+#   services/network/cloudflare-zero-trust/   — WARP Connector
+#   services/network/tailscale/               — Tailscale subnet router
+#
+# TOKEN: Zero Trust Dashboard → Networks → Tunnels → your tunnel
+#   → Install and run a connector → copy the token
+#   Docs: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
 # ===========================================================================
 
-# Tunnel token from Cloudflare Zero Trust dashboard
-# Get one at: https://one.dash.cloudflare.com/ → Networks → Tunnels → Create
-CLOUDFLARE_TUNNEL_TOKEN=YOUR_TUNNEL_TOKEN_HERE
+# Cloudflare tunnel token — get this from the Zero Trust dashboard
+CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiREFDS0VSVE9LRU4iLCJ0IjoiUkVQTEFDRV9NRSJ9
 
 TZ=America/New_York

services/network/cloudflare-zero-trust/.env.example

@@ -0,0 +1,23 @@
+# ===========================================================================
+# Cloudflare Zero Trust WARP Connector — Environment Variables
+# Copy to .env and fill in real values. .env is gitignored.
+#
+# This is the WARP Connector tunnel (private network access for WARP clients).
+# It is separate from the public-facing tunnel in infra/cloudflared/.
+# You need a SEPARATE tunnel token created specifically for the WARP connector.
+#
+# See the docker-compose.yml header for the full setup walkthrough.
+#
+# IMPORTANT: Do NOT reuse the token from infra/cloudflared — each tunnel
+# must have its own unique token. Create a new tunnel in the Zero Trust
+# dashboard specifically for this WARP connector.
+#
+# TOKEN LOCATION: Zero Trust Dashboard → Networks → Tunnels
+#   → Your connector tunnel → Click the tunnel → Overview tab
+#   → Install and run a connector → Copy the token value
+# ===========================================================================
+
+# Tunnel token for the WARP connector tunnel (NOT the same as infra/cloudflared)
+CF_TUNNEL_TOKEN=eyJhIjoiREFDS0VSVE9LRU4iLCJ0IjoiUkVQTEFDRV9NRSJ9
+
+TZ=America/New_York

services/network/cloudflare-zero-trust/docker-compose.yml

@@ -0,0 +1,78 @@
+# ===========================================================================
+# Cloudflare Zero Trust — WARP Connector (private network access)
+# Port: none (outbound-only to Cloudflare's network)
+# Docs: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/warp-connector/
+#
+# WHAT THIS IS (and how it differs from infra/cloudflared):
+#
+#   infra/cloudflared   = Cloudflare Tunnel: exposes specific HTTP services
+#                         to the public internet via public hostnames.
+#                         Anyone on the internet can reach immich.yourdomain.com.
+#
+#   THIS SERVICE        = WARP Connector: exposes your entire private network
+#                         to devices running the Cloudflare WARP client.
+#                         Only YOUR devices (enrolled in your Zero Trust org)
+#                         can reach 192.168.x.x addresses through it.
+#                         Works like Tailscale but via Cloudflare's network.
+#
+# USE CASE:
+#   Install Cloudflare WARP on your phone/laptop. Once connected to your
+#   Zero Trust org, you can SSH to your server by private IP, reach any
+#   homelab service on any port (not just HTTP), and use Split Tunneling
+#   to only route homelab traffic through Cloudflare.
+#
+# HOW IT COMPARES:
+#   CF Zero Trust WARP  — Cloudflare-managed mesh, Zero Trust policies,
+#                         device posture checks, identity-aware access
+#   Tailscale           — Self-managed mesh (via Tailscale infra), simpler,
+#                         faster setup, no Cloudflare dependency
+#   wg-easy             — Fully self-hosted WireGuard, needs open UDP port
+#
+# SETUP (one-time — do this before starting the container):
+#   1. Create a Zero Trust account at https://one.dash.cloudflare.com
+#      (free for up to 50 users)
+#   2. Go to Settings → WARP Client → Device enrollment policies
+#      Add a policy allowing your email address
+#   3. Go to Networks → Tunnels → Create a tunnel → Cloudflared
+#      Name it e.g. "homelab-warp-connector"
+#   4. In the tunnel, go to Private Network tab
+#      Add your LAN subnet: e.g. 192.168.1.0/24
+#   5. Enable WARP routing: Settings → WARP Client → Enable WARP to WARP
+#   6. Copy the tunnel token and add it to your .env as CF_TUNNEL_TOKEN
+#   7. make up SERVICE=network/cloudflare-zero-trust
+#   8. Install Cloudflare WARP on your devices:
+#      https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/download-warp/
+#   9. Log in to your Zero Trust org in the WARP client
+#  10. Done — you can now reach 192.168.x.x from your phone
+#
+# SPLIT TUNNELING (recommended):
+#   In Zero Trust dashboard → Settings → WARP Client → Profile settings
+#   → Split Tunnels → Exclude IPs: add your LAN subnet
+#   This routes only homelab traffic through WARP; all other internet
+#   traffic goes directly (faster, privacy-preserving).
+# ===========================================================================
+
+services:
+  cloudflare-zero-trust:
+    image: cloudflare/cloudflared:latest
+    container_name: cloudflare-zero-trust
+    restart: unless-stopped
+    pull_policy: always
+    # host networking lets the connector act as a subnet router and
+    # forward packets to all LAN hosts on behalf of WARP clients.
+    network_mode: host
+    cap_add:
+      - NET_ADMIN
+      - SYS_MODULE
+    sysctls:
+      - net.ipv4.ip_forward=1             # required for subnet routing
+      - net.ipv4.conf.all.src_valid_mark=1
+    command: tunnel --no-autoupdate run --token ${CF_TUNNEL_TOKEN}
+    environment:
+      TZ: ${TZ:-America/New_York}
+    healthcheck:
+      test: ["CMD", "cloudflared", "tunnel", "info"]
+      interval: 60s
+      timeout: 10s
+      retries: 3
+      start_period: 30s

services/network/tailscale/.env.example

@@ -0,0 +1,29 @@
+# ===========================================================================
+# Tailscale — Environment Variables
+# Copy to .env and fill in real values. .env is gitignored.
+#
+# SETUP STEPS:
+#   1. Sign up at https://login.tailscale.com (free for personal use)
+#   2. Go to Admin Console → Settings → Keys → Generate auth key
+#      - Check "Reusable" (so it survives container restarts)
+#      - Check "Pre-authorized" (so the machine auto-approves)
+#      - Expiry: 90 days is a good balance (rotate it occasionally)
+#   3. Paste the key below as TS_AUTHKEY
+#   4. Set TS_ROUTES to your LAN subnet (check your router: typically
+#      192.168.0.0/24, 192.168.1.0/24, or 10.0.0.0/24)
+#   5. After starting, go to Admin Console → Machines → approve subnet route
+# ===========================================================================
+
+# Reusable auth key from https://login.tailscale.com/admin/settings/keys
+# Format: tskey-auth-kXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+TS_AUTHKEY=tskey-auth-REPLACE_ME
+
+# Hostname shown in your Tailscale admin console and used for MagicDNS
+TS_HOSTNAME=homelab
+
+# Your homelab LAN subnet — adjust to match your router's network
+# Check with: ip route | grep -v tailscale | head -5
+TS_ROUTES=192.168.1.0/24
+
+TZ=America/New_York
+DATA_PATH=/mnt/nas/appdata

services/network/tailscale/docker-compose.yml

@@ -0,0 +1,72 @@
+# ===========================================================================
+# Tailscale — Zero-config mesh VPN for secure remote access
+# Port: none (outbound WireGuard connections only)
+# Docs: https://tailscale.com/kb/1282/docker
+#
+# Tailscale creates a private WireGuard mesh between all your devices
+# (phone, laptop, work PC) and your homelab server. No port forwarding,
+# no static IPs, no certificate management. Every device gets a stable
+# 100.x.x.x address and a MagicDNS hostname.
+#
+# This container runs as a SUBNET ROUTER, which means it exposes your
+# entire homelab LAN (e.g. 192.168.1.0/24) to all your Tailscale devices.
+# You can reach any service by LAN IP or by the server's Tailscale hostname.
+#
+# How it compares to alternatives:
+#   Tailscale       — mesh VPN, no firewall changes, best for personal devices
+#   wg-easy         — self-hosted WireGuard, more control, needs port forwarding
+#   Cloudflare Tunnel — HTTP only (no raw TCP/UDP), browser-focused access
+#   CF Zero Trust   — WARP connector, same mesh concept but via Cloudflare
+#
+# Quick start:
+#   1. Create a free Tailscale account at https://login.tailscale.com
+#   2. Generate an auth key: Admin Console → Settings → Keys → Auth keys
+#      Check "Reusable" so the container can re-authenticate after restart.
+#   3. cp .env.example .env  and fill in TS_AUTHKEY and TS_ROUTES
+#   4. make up SERVICE=network/tailscale
+#   5. In Tailscale Admin Console → Machines, approve the new "homelab" device
+#   6. Enable subnet routes: click the machine → "..." → Edit route settings
+#      Toggle on the advertised subnet route
+#   7. Optionally enable as exit node for internet routing through the server
+#
+# After setup, from any device in your Tailnet:
+#   ssh user@homelab                    # SSH via MagicDNS hostname
+#   http://100.x.x.x:8096             # Jellyfin via Tailscale IP
+#   http://homelab.tail1234.ts.net:8096 # Jellyfin via MagicDNS FQDN
+# ===========================================================================
+
+services:
+  tailscale:
+    image: tailscale/tailscale:latest
+    container_name: tailscale
+    hostname: ${TS_HOSTNAME:-homelab}
+    restart: unless-stopped
+    pull_policy: always
+    cap_add:
+      - NET_ADMIN
+      - NET_RAW
+    # host networking gives the subnet router access to all LAN interfaces
+    # and lets it advertise routes on behalf of the entire server.
+    network_mode: host
+    environment:
+      TZ: ${TZ:-America/New_York}
+      TS_AUTHKEY: ${TS_AUTHKEY}               # REQUIRED — from Tailscale admin console
+      TS_HOSTNAME: ${TS_HOSTNAME:-homelab}
+      TS_STATE_DIR: /var/lib/tailscale
+      TS_USERSPACE: "false"                   # kernel-mode WireGuard (faster, requires NET_ADMIN)
+      TS_ACCEPT_DNS: "true"                   # use Tailscale MagicDNS
+      # Advertise your homelab LAN as a subnet route (adjust to your subnet).
+      # After startup, approve the route in the Tailscale Admin Console.
+      TS_ROUTES: ${TS_ROUTES:-192.168.1.0/24}
+      # Uncomment to also advertise this server as a Tailscale exit node
+      # (routes all internet traffic from other devices through this server):
+      # TS_EXTRA_ARGS: --advertise-exit-node
+    volumes:
+      - ${DATA_PATH:-/mnt/nas/appdata}/tailscale/state:/var/lib/tailscale
+      - /dev/net/tun:/dev/net/tun              # kernel TUN device for WireGuard
+    healthcheck:
+      test: ["CMD", "tailscale", "status"]
+      interval: 60s
+      timeout: 10s
+      retries: 3
+      start_period: 30s