# 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) 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.

## 5) 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.

## 6) 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.

## 7) 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).

## 8) 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.