gitea-migration/setup/nginx-to-caddy/USAGE_GUIDE.md

Usage Guide: Nginx to Caddy Migration

This guide helps you migrate safely without big-bang risk.

1) Collect Nginx inventory

Run from your admin machine:

cd setup/nginx-to-caddy
./extract_nginx_inventory.sh --host=<nginx-host-ip> --user=<ssh-user> --port=22 --yes

You will get:

• output/nginx-full.conf
• output/etc-nginx.tar.gz
• output/inventory-summary.txt

2) Generate initial Caddyfile

For Cloudflare DNS-01 flow:

./nginx_to_caddy.sh \
  --input=./output/nginx-full.conf \
  --output=./output/Caddyfile.generated \
  --warnings=./output/conversion-warnings.txt \
  --tls-mode=cloudflare \
  --yes

Review warnings:

cat ./output/conversion-warnings.txt

If warnings include rewrite/regex/auth directives, expect manual edits.

3) Validate generated config

If caddy is not installed locally, use Docker:

./validate_caddy.sh --config=./output/Caddyfile.generated --docker

If local caddy is installed:

./validate_caddy.sh --config=./output/Caddyfile.generated

4) Use the recommended baseline

This toolkit now includes a hardened baseline at:

• setup/nginx-to-caddy/Caddyfile.recommended

Use it when you want a production-style config instead of a raw 1:1 conversion. You can either:

1. use it directly (if hostnames/upstreams already match your environment), or
2. copy its common snippets and service patterns into your live Caddyfile.

Validate it before deployment:

./validate_caddy.sh --config=./Caddyfile.recommended --docker

5) Canary migration (recommended)

Migrate one low-risk subdomain first:

1. Copy only one site block from generated Caddyfile to your live Caddy config.
2. Point only that DNS record to Caddy target.
3. Verify:
   • TLS cert valid
   • page loads
   • API/websocket calls work
4. Keep Nginx serving all other subdomains.

6) Full migration after canary success

When the canary is stable:

1. Add remaining site blocks.
2. Move DNS entries in batches.
3. Keep Nginx config snapshots for rollback.
4. Decommission Nginx only after monitoring period.

7) Rollback plan

If a site fails after cutover:

1. Repoint affected DNS entry back to Nginx endpoint.
2. Restore previous Nginx server block.
3. Investigate conversion warnings for that block.

8) Domain/TLS note for your current setup

You confirmed the domain is privacyindesign.com.

If you use TLS_MODE=cloudflare with Caddy, ensure:

• Caddy site labels use *.privacyindesign.com or specific subdomains under it.
• Cloudflare token has DNS edit on the same zone.
• DNS records point to the Caddy ingress path you intend (direct or via edge proxy).

9) Suggested next step for Phase 8

Given your current repo config:

• keep Phase 8 Caddy focused on source.privacyindesign.com
• migrate broader Nginx estate separately with this toolkit

That keeps Gitea cutover small and lowers blast radius.