112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./nginx_to_caddy.sh \
|
|
--input=./output/nginx-full.conf \
|
|
--output=./output/Caddyfile.generated \
|
|
--warnings=./output/conversion-warnings.txt \
|
|
--tls-mode=cloudflare \
|
|
--yes
|
|
```
|
|
|
|
Review warnings:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./validate_caddy.sh --config=./output/Caddyfile.generated --docker
|
|
```
|
|
|
|
If local `caddy` is installed:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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.
|