ray/hermes-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial commit

Browse Source
This commit is contained in:
ray
2026-07-12 10:17:17 -04:00
commit dab5a4ebc6
1424 changed files with 330463 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/vps-reverse-proxy/SKILL.md
+501
View File
@@ -0,0 +1,501 @@
---
name: vps-reverse-proxy
description: "Route all self-hosted services through a cheap VPS reverse proxy via Tailscale — zero ports open on home router, SSL on the VPS, services stay at home."
version: 1.1.0
author: ray
platforms: [linux]
created_by: "agent"
category: devops
metadata:
hermes:
tags: [vps, reverse-proxy, tailscale, nginx, ssl, duckdns, self-hosting]
---
# VPS Reverse Proxy for Self-Hosted Services
Route all self-hosted services (Immich, Paperless, Home Assistant, Mealie, etc.) through a cheap cloud VPS. The VPS acts as the public entry point — nginx with Let's Encrypt SSL — and tunnels traffic to the home server via Tailscale. Home router has zero ports open to the internet.
## When to use
- User has multiple self-hosted services (10+ nginx sites) exposed via port forwarding on their home router
- User wants to hide their home IP, reduce attack surface, and absorb DDoS at the VPS
- User already has Tailscale connecting home server and wants to extend it
- User has a cheap VPS ($4-6/mo) with 4GB+ RAM, 30GB+ disk, 1TB+ bandwidth
## Architecture
```
Internet → VPS (ports 80 + 443 only, nginx SSL)
↳ Tailscale WireGuard tunnel (41641 UDP)
↳ Home server (zero ports open to internet)
↳ Immich:2283, Paperless:8010, HA:8123, Mealie:3449, etc.
```
All service data stays on the home server. The VPS only runs nginx + certbot + Tailscale. Bandwidth: a VPS with 32TB/mo handles Immich photo browsing (23K assets) and all other services without issue.
## Prerequisites
- VPS with Ubuntu (OVH, Contabo, Hetzner, DigitalOcean — any provider)
- Root or sudo SSH access to the VPS
- Tailscale account with home server already on the tailnet
- DuckDNS domain (or any domain with API-updatable DNS)
## Step 1: Provision VPS
Order the cheapest instance with 4GB+ RAM. OVH VPS Starter or Contabo VPS S are ~$5/mo. Note the public IPv4 address.
## Step 2: Initial VPS setup
```bash
# SSH in as provided user (ubuntu on OVH cloud images)
ssh ubuntu@<vps-ip>
# Install essentials
sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx curl ufw
# Firewall — only 22, 80, 443
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
```
## Step 3: Tailscale
```bash
curl -fsSL https://tailscale.com/install.sh | sudo sh
sudo tailscale up --accept-routes --accept-dns=false
```
This prints an auth URL. Open it in a browser already logged into Tailscale. After auth, verify the home server is reachable:
```bash
tailscale status
# Should show: rayserver 100.93.253.36 linux -
curl http://100.93.253.36:2283/api/server/ping
# {"res":"pong"}
```
### Tailscale flags
- `--accept-routes`: lets VPS reach subnets advertised by other tailnet nodes
- `--accept-dns=false`: prevent Tailscale from overwriting `/etc/resolv.conf` (keep VPS DNS for Let's Encrypt challenges)
## Step 4: DNS
### Option A: Porkbun domain (recommended for >5 services)
DuckDNS caps at 5 entries. **IMPORTANT:** The DuckDNS update cron job must target the VPS IP explicitly, not auto-detect (which records the home IP). See `references/duckdns-vps-ip.md`.. For 6+ services, use a proper domain (~$11/yr at Porkbun). Porkbun supports wildcard DNS — one `*.graj-media.com` A record covers all subdomains.
**Porkbun API setup** — requires three things:
1. API key from Porkbun → Account → API Access
2. Secret API key from the same page
3. Domain API access enabled: Porkbun → Account Settings → "Allow API access for all domains"
**DNS creation via API** — first delete any parking records, then add A records:
```bash
# Delete parking/default records (CNAME/ALIAS pointing to uixie.porkbun.com)
curl -sk -X POST "https://api.porkbun.com/api/json/v3/dns/retrieve/graj-media.com" \
-d '{"apikey":"pk1_...","secretapikey":"sk1_..."}' | jq '.records[] | select(.type=="CNAME" or .type=="ALIAS") | .id'
# Delete each
curl -sk -X POST "https://api.porkbun.com/api/json/v3/dns/delete/graj-media.com/<id>" \
-d '{"apikey":"pk1_...","secretapikey":"sk1_..."}'
# Add wildcard A record
curl -sk -X POST "https://api.porkbun.com/api/json/v3/dns/create/graj-media.com" \
-d '{"apikey":"pk1_...","secretapikey":"sk1_...","name":"*","type":"A","content":"51.81.84.34","ttl":300}'
# Add root A record
curl -sk -X POST "https://api.porkbun.com/api/json/v3/dns/create/graj-media.com" \
-d '{"apikey":"pk1_...","secretapikey":"sk1_...","name":"","type":"A","content":"51.81.84.34","ttl":300}'
```
**Pitfall:** Porkbun returns `"conflict"` errors if parking/default CNAME/ALIAS records exist. Delete them first, then add A records.
**Pitfall:** If the API returns `"Domain is not opted in to API access"`, go to Porkbun → Account Settings and enable the global API access toggle (separate from the API key generation page).
### Option B: DuckDNS (free, max 5 entries)
DuckDNS does NOT support dotted subdomains (`immich.grajmedia.duckdns.org`). Use the **hyphen format** instead: `immich-grajmedia.duckdns.org`.
On [duckdns.org](https://duckdns.org), add all domains comma-separated in the domains field:
```
grajmedia,immich-grajmedia,paperless-grajmedia,ha-grajmedia,shopproquote-grajmedia,mealie-grajmedia,audiobookshelf-grajmedia
```
Set the IP to the VPS public IP. Update. Verify:
```bash
dig +short immich-grajmedia.duckdns.org @1.1.1.1
# Should return VPS IP
```
## Step 5: nginx reverse proxy configs
Each service gets its own nginx server block with its own DuckDNS subdomain. Port mappings from Tailscale IP to home server:
| Service | Home server port | VPS domain |
|---------|-----------------|------------|
| Immich | 2283 (direct) | immich-grajmedia.duckdns.org |
| Paperless | 8010 (direct) | paperless-grajmedia.duckdns.org |
| Home Assistant | 8123 (direct) | ha-grajmedia.duckdns.org |
| Mealie | 3449 (home nginx SSL) | mealie-grajmedia.duckdns.org |
| Audiobookshelf | 13378 (direct) | audiobookshelf-grajmedia.duckdns.org |
| ShopProQuote | 443 (home nginx SSL) | shopproquote-grajmedia.duckdns.org |
### Template for direct-HTTP services
Most Docker services expose HTTP on a port (Immich, Paperless, HA, Audiobookshelf):
```nginx
server {
listen 80;
server_name <service>-grajmedia.duckdns.org;
client_max_body_size 500M;
location / {
proxy_pass http://100.93.253.36:<port>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 86400;
proxy_buffering off;
}
}
```
### Template for home-nginx-SSL services (DuckDNS)
Some services sit behind the home server's nginx with SSL only (Mealie on 3449, ShopProQuote on 443). The VPS must proxy via HTTPS. For DuckDNS subdomains (`<service>-grajmedia.duckdns.org`), the home server nginx only knows the DuckDNS name, so the VPS must hardcode the Host header and SNI name:
```nginx
server {
listen 80;
server_name <service>-grajmedia.duckdns.org;
client_max_body_size 500M;
location / {
proxy_pass https://100.93.253.36:<ssl_port>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host grajmedia.duckdns.org;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_ssl_verify off;
proxy_ssl_server_name on;
proxy_ssl_name grajmedia.duckdns.org;
proxy_read_timeout 86400;
proxy_buffering off;
}
}
```
The critical directives for DuckDNS-style HTTPS proxying to home nginx:
- `proxy_ssl_verify off` — home nginx uses Let's Encrypt for `grajmedia.duckdns.org`, not the Tailscale IP
- `proxy_ssl_server_name on` + `proxy_ssl_name grajmedia.duckdns.org` — SNI hostname the home nginx expects
- `proxy_set_header Host grajmedia.duckdns.org` — hardcoded to match the home nginx server_name (DuckDNS subdomains are NOT known to home nginx; only the base DuckDNS domain is)
### Template for home-nginx-SSL services (custom domain)
When using a custom domain like `graj-media.com` with per-subdomain Let's Encrypt certs on the VPS, forward the original Host header. Each subdomain (`mealie.graj-media.com`, `vault.graj-media.com`, `plex.graj-media.com`) must ALSO be added as a `server_name` on the home server's nginx config:
**VPS nginx:**
```nginx
server {
server_name <service>.graj-media.com;
client_max_body_size 100M;
location / {
proxy_pass https://100.93.253.36:<home_port>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host; # forward original subdomain
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_ssl_verify off;
proxy_ssl_server_name on;
proxy_ssl_name grajmedia.duckdns.org; # home nginx cert SAN
proxy_read_timeout 86400;
proxy_buffering off;
}
listen 443 ssl; # managed by Certbot
ssl_certificate /etc/letsencrypt/live/<service>.graj-media.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/<service>.graj-media.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
```
**Home server nginx — must include the subdomain in server_name:**
```nginx
server {
listen <port> ssl;
server_name grajmedia.duckdns.org <service>.graj-media.com; # ← CRITICAL
# ... rest of the config
}
```
Key differences from DuckDNS template:
- `proxy_set_header Host $host;` — forward the original subdomain, NOT a hardcoded value. The home nginx matches it via `server_name`.
- Each subdomain gets its own Let's Encrypt cert on the VPS (certbot `-d <service>.graj-media.com`)
- The home server's `server_name` must include `<service>.graj-media.com` — always verify this when adding a new subdomain.
Enable each site and test:
```bash
sudo ln -sf /etc/nginx/sites-available/<service> /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t && sudo systemctl reload nginx
```
Test each before DNS propagates:
```bash
curl -s -o /dev/null -w '%{http_code}' -H 'Host: <service>-grajmedia.duckdns.org' http://localhost/
```
## Step 6: Let's Encrypt SSL
After DNS propagates for all subdomains, provision SSL for all at once:
```bash
sudo certbot --nginx --non-interactive --agree-tos --email <email> \
-d grajmedia.duckdns.org \
-d immich-grajmedia.duckdns.org \
-d paperless-grajmedia.duckdns.org \
-d ha-grajmedia.duckdns.org \
-d shopproquote-grajmedia.duckdns.org \
-d mealie-grajmedia.duckdns.org \
-d audiobookshelf-grajmedia.duckdns.org
```
Certbot auto-renews. It edits the nginx configs to add `listen 443 ssl` and the cert paths.
### Adding a new subdomain to an existing multi-domain cert
When you already have a cert covering N subdomains and need to add one more (e.g. adding `gitea.graj-media.com` to an existing `graj-media.com` cert), use `--expand`:
```bash
# 1. Create the nginx server block on the VPS first (certbot needs it to exist)
ssh ubuntu@<vps-ip> 'sudo tee /etc/nginx/sites-available/<new-service> > /dev/null << '\''EOF'\''
server {
server_name <new-service>.graj-media.com;
client_max_body_size 512M;
location / {
proxy_pass https://100.93.253.36:<home_port>;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_ssl_verify off;
proxy_read_timeout 86400;
proxy_buffering off;
}
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/graj-media.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/graj-media.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
EOF
sudo ln -sf /etc/nginx/sites-available/<new-service> /etc/nginx/sites-enabled/'
# 2. Expand the existing cert — list ALL existing domains PLUS the new one
ssh ubuntu@<vps-ip> 'sudo certbot certonly --nginx --non-interactive --agree-tos \
--email <email> \
--cert-name graj-media.com \
-d graj-media.com \
-d existing1.graj-media.com \
-d existing2.graj-media.com \
-d existing3.graj-media.com \
-d <new-service>.graj-media.com'
# 3. Reload nginx on the VPS
ssh ubuntu@<vps-ip> 'sudo systemctl reload nginx'
# 4. Add the new subdomain to the HOME server's nginx server_name
# (on the home server, edit the service's nginx config)
sudo nginx -t && sudo systemctl reload nginx
```
**Pitfall:** The `--expand` flag is required when adding domains to an existing cert, NOT `--force-renewal` or bare `certonly`. Without `--expand`, certbot creates a separate cert file instead of extending the existing one. The nginx `ssl_certificate` paths remain the same (certbot updates the live symlink), so no config changes needed.
**Pitfall:** List ALL existing domains every time. Omitting one drops it from the renewed cert. Use `openssl x509 -in /etc/letsencrypt/live/<cert-name>/fullchain.pem -noout -text | grep DNS:` to see the current SANs before expanding.
**Pitfall:** The VPS nginx server block for the new subdomain MUST exist before running certbot — certbot uses the nginx plugin to verify the domain. Create the config first (it can point to a non-existent backend for a moment), run certbot (which adds the SSL directives), then ensure the proxy config is correct.
**Pitfall:** For custom domains (graj-media.com), the VPS cert is a multi-domain cert (NOT a wildcard). Each new subdomain requires an explicit certbot expand. DNS wildcard records (`*.graj-media.com`) handle routing but NOT certificate coverage — certbot must still list every subdomain in the `-d` flags.
## Step 8: ShopProQuote LLM proxy
If ShopProQuote calls `/llm/` to a local Ollama on the home server, add a location block to the ShopProQuote nginx config on the VPS:
```nginx
location /llm/ {
proxy_pass http://100.93.253.36:11434/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_read_timeout 120;
}
```
## Step 9: Static sites (no Docker backend)
For static HTML/CSS/JS sites served directly by nginx (no Docker container), see `references/static-site-deployment.md` for the complete pattern including home nginx `root` + `try_files`, file permissions, VPS HTTPS proxy, and certbot per-subdomain SSL.
## Step 10: Landing page
Create a simple HTML landing page at `grajmedia.duckdns.org` linking to all services:
```nginx
server {
listen 80;
server_name grajmedia.duckdns.org;
location = / {
return 200 '<!DOCTYPE html>
<html><head><title>grajmedia</title>
<style>body{font-family:-apple-system,sans-serif;max-width:600px;margin:60px auto;padding:20px;background:#111;color:#eee}
a{color:#4fc3f7;text-decoration:none;display:block;padding:8px 0;font-size:18px}
a:hover{color:#81d4fa}h1{font-size:28px;margin-bottom:24px}</style></head>
<body><h1>grajmedia services</h1>
<a href=https://immich-grajmedia.duckdns.org>Immich — photos</a>
<a href=https://paperless-grajmedia.duckdns.org>Paperless — documents</a>
<a href=https://ha-grajmedia.duckdns.org>Home Assistant</a>
<a href=https://mealie-grajmedia.duckdns.org>Mealie — recipes</a>
<a href=https://audiobookshelf-grajmedia.duckdns.org>Audiobookshelf</a>
<a href=https://shopproquote-grajmedia.duckdns.org>ShopProQuote</a>
</body></html>';
add_header Content-Type text/html;
}
}
```
### Updating the landing page
The page is rendered via `return 200 '...'` in nginx. To add or remove services, edit `/etc/nginx/sites-available/grajmedia` and reload nginx.
## Post-migration: clean up home server
After verifying all services are accessible through the VPS:
1. **Remove port forwards** on the ASUS router — no more ports 443, 3443-3450 exposed
2. **Optionally remove SSL from home nginx** — services are now accessed via VPS SSL, so home nginx can drop to HTTP-only (simpler config, faster local access)
3. **Keep Tailscale running** — it's the backbone of the tunnel
## Security hardening the VPS
The VPS is the public face of all services. Apply these hardening steps to any service exposed through the VPS.
### Hide nginx version
```bash
sudo sed -i 's/server_tokens build;/server_tokens off;/' /etc/nginx/nginx.conf
sudo nginx -t && sudo systemctl reload nginx
```
### Add rate limiting
Add a zone to the http block in `/etc/nginx/nginx.conf`:
```nginx
limit_req_zone $binary_remote_addr zone=<zone_name>:10m rate=5r/m;
```
Apply per-service in each server block:
```nginx
limit_req zone=<zone_name> burst=5 nodelay;
```
### Security headers
Add to the location block of each VPS nginx server block. Headers at the server block level may be dropped when a location block with `proxy_pass` exists — put them inside `location`:
```nginx
location / {
# ... proxy_pass, proxy_set_header directives ...
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=(), midi=(), sync-xhr=(), clipboard-read=(), clipboard-write=()" always;
}
```
### Install fail2ban for nginx HTTP auth
The default nginx-http-auth filter watches **error.log** (not access.log):
```bash
sudo apt-get install -y fail2ban
sudo tee /etc/fail2ban/jail.d/nginx-http-auth.conf << 'EOF'
[nginx-http-auth]
enabled = true
port = http,https
filter = nginx-http-auth
logpath = /var/log/nginx/error.log
maxretry = 5
bantime = 3600
findtime = 300
EOF
sudo systemctl restart fail2ban
```
Verify: `sudo fail2ban-client status nginx-http-auth`
### Pitfall: `sites-enabled` is a copy, not a symlink
When a VPS nginx site config is created as a **separate file** in `sites-enabled/` (rather than a symlink to `sites-available/`), future edits to `sites-available/` are silently ignored. nginx continues reading the stale copy.
```bash
# Check
ls -la /etc/nginx/sites-enabled/<service>
# "-rw-r--r--" = copy (bad), "lrwxrwxrwx" = symlink (good)
# Fix
sudo rm /etc/nginx/sites-enabled/<service>
sudo ln -s /etc/nginx/sites-available/<service> /etc/nginx/sites-enabled/<service>
sudo nginx -t && sudo systemctl reload nginx
```
This affects the `sudo ln -sf` command in the enable step — if the site was originally created by a process that writes files directly (e.g., certbot, manual copy, migration from another host), it may be a standalone file.
## Pitfalls
- **Subdomain server_name mismatch (custom domain)**: When adding a new subdomain on the VPS (SSL cert + nginx server block), you MUST also add that subdomain to the HOME server nginx server_name for the target service. Without this, the home nginx routes traffic to the default server block (404 or wrong content). Fix: update the home nginx server_name to include <subdomain>.graj-media.com, then reload nginx. Verify with `curl -sI -H 'Host: <subdomain>.graj-media.com' http://localhost:<home_port>`.
- **VPS Host header uses bare apex domain instead of $host or subdomain**: When hand-writing a VPS nginx config for a custom-domain subdomain, it's easy to write `proxy_set_header Host graj-media.com;` (just the root domain) instead of `proxy_set_header Host $host;` (forwards the original subdomain verbatim). This drops the subdomain prefix, so the home nginx never matches the server_name. **Symptoms**: the request hits the home nginx default server block (often a 404 or wrong service) instead of the intended one. **Fix**: use `proxy_set_header Host $host;` on the VPS (for custom domain with per-subdomain certs) or hardcode the base DuckDNS domain (for the DuckDNS pattern). **Diagnostic**: SSH into the home server and run `curl -sI -H 'Host: mealie.graj-media.com' http://localhost:9925/` — if the service responds correctly locally, the problem is the Host header sent by the VPS. <br><br>**Three-way decision for Host header on VPS**:<br>1. `proxy_set_header Host $host;` — use when the VPS has its own per-subdomain cert AND the home server's server_name includes that subdomain. This preserves the original hostname through the chain.<br>2. `proxy_set_header Host grajmedia.duckdns.org;` — use when the VPS uses a DuckDNS subdomain and the home server's server_name is only the base DuckDNS domain. The home nginx doesn't know about the hyphenated DuckDNS subdomain, so you hardcode the one name it recognizes.<br>3. `proxy_set_header Host <bare-apex>;` — NEVER use this. The bare apex (e.g., `graj-media.com`) matches no server block on the home server. If you see this, it's almost certainly a copy-paste or manual-entry error.
- **DuckDNS auto-detects source IP**: When the DuckDNS update script runs on the home server with `&ip=` (empty), DuckDNS uses the request's source IP — which is the HOME IP, not the VPS IP. For VPS reverse proxy setups, you MUST hardcode the VPS IP in the update URL: `&ip=51.81.84.34`. Otherwise the domain resolves to the home IP and bypasses the VPS entirely. Fix the cron script to always send the VPS IP.
- **DuckDNS doesn't support dotted subdomains**: `immich.grajmedia.duckdns.org` won't resolve. Use hyphen format: `immich-grajmedia.duckdns.org`.
- **DuckDNS auto-detects wrong IP**: The update script's `&ip=` parameter auto-detects the request's source IP. If the script runs on the home server but the domain should point to the VPS, DuckDNS sets the record to the home IP instead. **Fix:** always hardcode the VPS IP: `&ip=<VPS_IP>`. Script is at `/opt/duckdns/update.sh`. Verify with `dig +short <domain> @8.8.8.8`.
- **/etc/hosts DNS override**: A local `/etc/hosts` entry like `127.0.0.1 grajmedia.duckdns.org` takes precedence over DNS. Useful for local access (avoids hairpin NAT), but causes confusion — `resolvectl query` shows "Data from: synthetic" when hosts file is active.
- **certbot mangles configs on domain switch**: When migrating from DuckDNS to a new domain, certbot has already modified the nginx config files to add SSL directives AND secondary server blocks for HTTP→HTTPS redirect. Simply changing `server_name` values leaves broken configs (`listen` directives outside server blocks, missing certs). **The fix**: `sudo rm /etc/nginx/sites-enabled/*`, rewrite all configs from scratch, then re-run certbot for the new domain.
- **Bash heredoc expansion in SSH commands**: Writing nginx configs via `ssh host "cat > file << 'EOF' ... $host ..."` may still expand `$host`, `$http_upgrade`, etc. because the double-quoted SSH wrapper triggers local expansion before the remote shell sees the heredoc. **Fix**: use single-quoted SSH: `ssh host 'cat > file << EOF ... $host ...'` (unquoted heredoc delimiter, but single-quoted SSH wrapper — the variable won't exist remotely so it stays literal), or patch the empty values afterwards with sed: `sudo sed -i 's|proxy_set_header Host ;|proxy_set_header Host \$host;|'`.
- **Home nginx is SSL-only**: When proxying from VPS to home server nginx, you must use HTTPS with `proxy_ssl_verify off` and proper SNI headers. Direct Docker ports (HTTP) are simpler when available.
- **127.0.0.1 Docker bindings**: Services bound to `127.0.0.1` are unreachable from Tailscale. Either bind to `0.0.0.0` or proxy through home nginx SSL. See `references/docker-port-binding.md`.
- **certbot NXDOMAIN**: If certbot fails with NXDOMAIN, the DNS entry doesn't exist yet. Add the subdomain on DuckDNS first, wait for propagation, retry.
- **OVH cloud images use `ubuntu` user by default**, not `root`. SSH keys go in `/home/ubuntu/.ssh/`, not `/root/.ssh/`. After key setup, use `sudo` to copy to root.
- **Vaultwarden deployment**: Complete worked example — Docker Compose, home nginx with WebSocket support, VPS nginx, SSL setup, post-deploy steps. See `references/vaultwarden.md`.\n- **Plex Media Server**: Host-networked Plex proxied through VPS — large file streaming, WebSocket, 401 auth flow. See `references/plex.md`.\n
- **Permanent certificate migration for Docker services**: When a Docker service like Vaultwarden uses Let's Encrypt certs managed by the host nginx (not by the container), the container doesn't need its own cert volume. Just bind-mount the data directory and let nginx handle SSL.
- **DuckDNS auto-IP picks the wrong server**: When running the DuckDNS update script on the home server, leaving the `&ip=` parameter empty makes DuckDNS auto-detect the request's source IP — which is the HOME IP, not the VPS. The domain then resolves to the home server directly, bypassing the VPS entirely. **Fix**: hardcode the VPS IP in the update URL: `&ip=51.81.84.34`. The cron script at `/opt/duckdns/update.sh` must use the explicit VPS IP, not auto-detect.
- **Let's Encrypt rate limits**: Certbot has a 5-certificates-per-domain-per-week limit. Bundle all subdomains into one cert (comma-separated `-d` flags) rather than separate certs per service.
- **nginx fails at boot with 'host not found in upstream'**: nginx resolves all upstream hostnames at startup. If DNS isn't ready yet (common at boot, especially with `resolv.conf` pointing to `127.0.0.53` and systemd-resolved still initializing), nginx refuses to start — and ONE bad upstream takes down ALL sites. Fix: use runtime DNS resolution with `resolver` + variable. See `references/nginx-runtime-dns.md` for the pattern and worked example.
- **Corporate firewall NRD (Newly Registered Domain) blocking**: Domains registered less than 30–60 days ago are blocked by most corporate web filters (Cisco Umbrella, FortiGuard, etc.) under the "Newly Registered and Observed Domains" category. This blocks ALL subdomains (`*.graj-media.com`) — the server config is fine, the block happens at the corporate DNS/firewall layer. No server-side fix exists. Workarounds: (1) Use an older well-established domain (like a years-old DuckDNS subdomain) as a temporary alias pointing to the same VPS — the NRD filter won't flag it. (2) Access directly via Tailscale IP (`https://100.93.253.36`) from work machines with Tailscale installed. (3) Ask corporate IT for a domain whitelist exception. The block lifts automatically once the domain ages past the NRD window (typically 30 days post-registration). See `references/duckdns-temp-alias.md` for the full temp-alias setup.
- **Host header mismatch → SPA redirect loop**: When the VPS `proxy_pass` sends a `Host` header that doesn't match the home server nginx `server_name`, the request lands on the wrong server block (or the default). In SPAs with auth (ShopProQuote, etc.), this manifests as an infinite redirect between `login.html` and `index.html` — the auth check fails because API calls hit a different nginx context, the cookie/localStorage domain doesn't match, or the default server block serves unexpected content. See `references/spa-redirect-loop.md` for the full diagnostic workflow, worked example, and three fix patterns (file rename + reference update, server alias, stub page cache-breaker). **Two fixes, use the one that fits: (A) Add the VPS domain as a server alias on the home nginx:** `server_name grajmedia.duckdns.org <vps-domain1> <vps-domain2>;` then `sudo nginx -t && sudo systemctl reload nginx`. This preserves the original Host header through the chain. **(B) Match the Host header to what home nginx expects:** `proxy_set_header Host grajmedia.duckdns.org;` in the VPS nginx config. Option A is preferred when you have multiple services — it keeps Host-based routing intact. **Always verify** the home nginx config's `server_name` and ensure the Host header reaching it resolves to the right server block. **Browser cache trap:** after all server-side fixes are applied, the user may STILL see the stale redirect because their browser cached the 302 from the old setup. Verify with `curl -skI https://domain/` — if the server returns 200 but the browser shows a redirect, the fix is a hard refresh (Ctrl+Shift+R) or clearing site data in DevTools. A stub page at the old redirect target with a `<meta http-equiv="refresh">` to the correct page + no-cache headers breaks the cached redirect without user intervention.