From e7371280287d1141f0a4a2f81a0aba1cbcd04608 Mon Sep 17 00:00:00 2001 From: S Date: Sun, 1 Mar 2026 11:08:10 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20update=20USAGE=5FGUIDE.md=20=E2=80=94?= =?UTF-8?q?=20Nginx=E2=86=92Caddy,=20ports=E2=86=92IPs,=20dynamic=20repos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- USAGE_GUIDE.md | 61 ++++++++++++++++++++++++-------------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md index 2193d6f..6f6819d 100644 --- a/USAGE_GUIDE.md +++ b/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 -- An Nginx Docker container is already running on Unraid +- Macvlan container IPs are available on the LAN (not already in use) +- 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". - -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. +**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. ### 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 -ssh USER@UNRAID_IP "test -f /path/to/nginx/conf.d/gitea.conf && echo exists || echo gone" +# Caddy container and config removed +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` -2. Add `"$REPO_4_NAME"` to the `REPOS=()` array in phases 4-9 -3. Run phases 4-9 for the new repo (existing repos will be skipped) +1. Append the new repo name to `REPO_NAMES` in `.env` (space-separated): `REPO_NAMES="repo1 repo2 new-repo"` +2. Run phases 4-9 (existing repos will be skipped, only the new one gets processed) ### 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 \ - -v /etc/letsencrypt:/etc/letsencrypt \ - -v /var/www/html:/var/www/html \ - certbot/certbot renew --quiet && \ - docker exec NGINX_CONTAINER nginx -s reload" +ssh USER@UNRAID_IP "cd /path/to/caddy && docker compose restart" ``` ---