docs: update USAGE_GUIDE.md — Nginx→Caddy, ports→IPs, dynamic repos

- Prerequisites: Nginx container→Cloudflare API token, ports→macvlan IPs
- Edge cases: replaced Nginx/Certbot troubleshooting with Caddy/TLS_MODE
- Rollback: Nginx config removal→Caddy container/config removal
- Day-to-day: replaced certbot renewal with Caddy auto-renewal
- Adding repos: REPO_4_NAME→append to REPO_NAMES

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

USAGE_GUIDE.md

@@ -28,8 +28,8 @@ Before running anything, confirm:
 - MacBook can SSH to Unraid: `ssh user@UNRAID_IP`
 - MacBook can SSH to Fedora: `ssh user@FEDORA_IP`
 - A DNS A record exists for your Gitea domain pointing to `UNRAID_IP`
-- Ports 3000 (Gitea web) and 2222 (Gitea SSH) are free on both servers
+- Macvlan container IPs are available on the LAN (not already in use)
-- An Nginx Docker container is already running on Unraid
+- If using `TLS_MODE=cloudflare`: a Cloudflare API token with Zone:DNS:Edit permission
 
 ### 2. GitHub Tokens
 
@@ -134,7 +134,7 @@ If you prefer to run each phase individually and inspect results:
 After the full migration completes:
 
 1. **HTTPS access**: Open `https://YOUR_DOMAIN` in a browser — you should see the Gitea login page with a valid SSL certificate.
-2. **Repository content**: Log in as admin, navigate to your org, confirm all 3 repos have commits, branches, and (if enabled) issues/labels.
+2. **Repository content**: Log in as admin, navigate to your org, confirm all repos have commits, branches, and (if enabled) issues/labels.
 3. **CI pipelines**: Create a test PR in one repo. Gitea Actions should run the migrated workflows. If Phase 9 ran, security scans (Semgrep, Trivy, Gitleaks) should also trigger.
 4. **GitHub mirrors**: Check your GitHub repos — the description should start with `[MIRROR]` and the latest commits should match Gitea.
 5. **Fedora mirrors**: SSH into the Fedora Gitea instance and verify repos exist under the admin user namespace.
@@ -210,11 +210,11 @@ MIGRATION_POLL_TIMEOUT_SEC=1800    # 30 minutes instead of default 10
 
 Then re-run Phase 4. Already-migrated repos will be skipped.
 
-### Port already in use on Unraid/Fedora
+### Container IP already in use
 
-**Symptom**: Preflight check 13 or 14 fails with "Port 3000 already in use".
+**Symptom**: Preflight check 13 warns that a macvlan IP is already responding to ping.
 
-**Fix**: Either stop whatever is using port 3000, or change `UNRAID_GITEA_PORT` / `FEDORA_GITEA_PORT` in `.env` to use a different port.
+**Fix**: Either release the conflicting IP or change the container IP in `.env` (`UNRAID_GITEA_IP`, `UNRAID_CADDY_IP`, `FEDORA_GITEA_IP`, or `FEDORA_CADDY_IP`).
 
 ### DNS doesn't resolve to Unraid IP
 
@@ -222,23 +222,20 @@ Then re-run Phase 4. Already-migrated repos will be skipped.
 
 **Fix**: Add or update your DNS A record. If using a local DNS server or `/etc/hosts`, ensure the record points to `UNRAID_IP`. DNS propagation can take minutes to hours.
 
-### Nginx config test fails in Phase 8
+### Caddy fails to start or obtain TLS certificate in Phase 8
 
-**Symptom**: Phase 8 aborts with "Nginx config test failed".
+**Symptom**: Phase 8 times out waiting for HTTPS to become available.
 
-**Fix**: The script automatically removes the bad config file. Check that `NGINX_CONF_PATH` in `.env` points to the correct `conf.d` directory inside the Nginx container's volume mount. Verify the Nginx container has `/etc/letsencrypt` mounted if using Let's Encrypt.
+Common causes (TLS_MODE=cloudflare):
+- `CLOUDFLARE_API_TOKEN` is invalid or lacks Zone:DNS:Edit permission
+- DNS zone is not managed by Cloudflare
+- Caddy container cannot reach Cloudflare API (firewall/proxy)
 
-### Certbot fails (Let's Encrypt)
+Common causes (TLS_MODE=existing):
+- `SSL_CERT_PATH` or `SSL_KEY_PATH` doesn't exist on the Unraid host
+- Certificate is expired or doesn't match `GITEA_DOMAIN`
 
-**Symptom**: Phase 8 fails at "Running Certbot".
+**Fix**: Check Caddy container logs: `ssh USER@UNRAID_IP "docker logs caddy"`. For Cloudflare issues, verify the API token at `dash.cloudflare.com`. For existing certs, verify the paths exist and the cert matches the domain.
-
-Common causes:
-- Port 80 is not reachable from the internet (firewall, router, ISP blocking)
-- DNS doesn't resolve to the server's public IP
-- Nginx container doesn't mount `/etc/letsencrypt` and `/var/www/html`
-- Rate limit: Let's Encrypt allows 5 certs per domain per week
-
-**Fix**: Verify port 80 is open (`curl http://YOUR_DOMAIN/.well-known/acme-challenge/test`), fix the DNS, or add the volume mounts to the Nginx container. If rate limited, wait or use `SSL_MODE=existing` with a cert from another provider.
 
 ### SSH to remote host fails
 
@@ -314,7 +311,7 @@ git push
 Tears down all phases from 9 to 1, prompting for confirmation at each phase. This:
 - Removes security workflows from repos
 - Restores GitHub repo settings (description, homepage, wiki, projects, Pages)
-- Removes Nginx config and SSL certs
+- Removes Caddy container, config, and TLS data
 - Removes branch protection rules
 - Removes push mirrors and re-enables GitHub Actions
 - Removes `.gitea/workflows/` from repos
@@ -338,7 +335,7 @@ To tear down Phases 5-9 but keep Gitea and repos (Phases 1-4):
 ./teardown_all.sh --through=5
 ```
 
-This removes security workflows, Nginx, branch protection, push mirrors, and Gitea workflows — but leaves the Gitea instances running with the migrated repos.
+This removes security workflows, Caddy, branch protection, push mirrors, and Gitea workflows — but leaves the Gitea instances running with the migrated repos.
 
 ### Teardown a single phase
 
@@ -438,8 +435,9 @@ curl -sf -H "Authorization: token $TOKEN" \
 # HTTPS should no longer work
 curl -sf https://YOUR_DOMAIN/api/v1/version       # Should fail
 
-# Nginx config removed
+# Caddy container and config removed
-ssh USER@UNRAID_IP "test -f /path/to/nginx/conf.d/gitea.conf && echo exists || echo gone"
+ssh USER@UNRAID_IP "docker ps --filter name=caddy --format '{{.Status}}'"  # Should be empty
+ssh USER@UNRAID_IP "test -f /path/to/caddy/Caddyfile && echo exists || echo gone"
 # Should print: gone
 
 # GitHub repos should be restored
@@ -483,9 +481,8 @@ sed -i 's/^GITEA_ADMIN_TOKEN=.*/GITEA_ADMIN_TOKEN=/' .env
 
 ### Adding a new repository
 
-1. Add `REPO_4_NAME=new-repo` to `.env`
+1. Append the new repo name to `REPO_NAMES` in `.env` (space-separated): `REPO_NAMES="repo1 repo2 new-repo"`
-2. Add `"$REPO_4_NAME"` to the `REPOS=()` array in phases 4-9
+2. Run phases 4-9 (existing repos will be skipped, only the new one gets processed)
-3. Run phases 4-9 for the new repo (existing repos will be skipped)
 
 ### Checking mirror sync status
 
@@ -499,14 +496,14 @@ curl -sf -X POST -H "Authorization: token $TOKEN" \
   http://UNRAID_IP:3000/api/v1/repos/ORG/REPO/push_mirrors-sync
 ```
 
-### Renewing SSL certificate manually
+### TLS certificate renewal
+
+When `TLS_MODE=cloudflare`, Caddy handles certificate renewal automatically — no manual action needed. Caddy renews certificates 30 days before expiry.
+
+When `TLS_MODE=existing`, replace the cert/key files at `SSL_CERT_PATH` and `SSL_KEY_PATH` on the Unraid host, then restart Caddy:
 
 ```bash
-ssh USER@UNRAID_IP "docker run --rm \
+ssh USER@UNRAID_IP "cd /path/to/caddy && docker compose restart"
-  -v /etc/letsencrypt:/etc/letsencrypt \
-  -v /var/www/html:/var/www/html \
-  certbot/certbot renew --quiet && \
-  docker exec NGINX_CONTAINER nginx -s reload"
 ```
 
 ---