Quick Start

This walks a single zone from read-only assessment all the way to a gated cutover. Every step before the DNS flip is non-destructive and produces artifacts you can review in git — in a private repository, since the output directory also carries generated key material.

You will need: a running edge host (its public IP), and a target stack to point at. No box yet? The Deploy / Landing Zone page stands one up with a single docker compose up.

1. Extract the zone (read-only)

export CLOUDFLARE_API_TOKEN=…            # a read-only token
flareover extract example.com > zone.snapshot.json

extract only reads. The snapshot is a faithful, provider-native capture of the zone: DNS records, TLS/SSL settings, WAF and rate-limit rules, page rules, transforms, redirects, object-storage buckets, and more.

Migrating a whole account? flareover zones lists every zone the token can see.

2. Assess: the honest coverage report

flareover assess zone.snapshot.json          # human-readable
flareover assess zone.snapshot.json --md      # Markdown (drop into a PR)
flareover assess zone.snapshot.json --json     # machine-readable findings
flareover assess zone.snapshot.json --html      # self-contained shareable report

Every setting gets exactly one verdict: AUTO, ASK, or MANUAL (see The Contract). assess is CI-friendly:

Exit code	Meaning
0	Everything is AUTO: a clean, fully-deterministic migration
11	There are ASK items to answer (no MANUAL)
10	There are MANUAL items to handle by hand

These codes are not only for assess

prepare and storage return them too, and execute refuses to authorise a cutover while MANUAL items are outstanding (exit 10, unless you pass --accept-manual). A shell chain like flareover prepare … && deploy will stop where you might expect it to continue — that is deliberate: a MANUAL item is a control the generated stack does not reproduce. Full table in the CLI Reference.

3. Resolve the ASK questions

flareover resolve zone.snapshot.json --defaults > decisions.lock

resolve walks each ASK question into a decisions.lock. On a terminal it is interactive; --defaults accepts the safe default for each, and --merge <file> layers onto an existing lock. Anything you leave unanswered simply is not generated, never guessed.

4. Estimate the cost (optional)

flareover cost zone.snapshot.json --vps 12    # your EU VPS price, €/mo

Compares the managed-edge tier/add-on spend against a flat EU-sovereign stack.

5. Prepare: generate the target config

flareover prepare zone.snapshot.json \
  --decisions decisions.lock \
  --edge-ip 203.0.113.10 \
  --ca actalis \
  --out ./out --validate

This writes the deployable artifacts (Caddyfile, caddy-waf rules, PowerDNS zone, …) plus a MIGRATION.md report: a table of every element found and exactly what it became (1:1 AUTO / answered-ASK / MANUAL). --validate proves the generated Caddyfile and zone actually parse.

Generation is a pure function of snapshot + decisions.lock: run it twice, get byte-identical config. Review ./out in git before anything goes live — except <out>/mesh/*.wg0.conf, which carry WireGuard private keys. prepare writes a .gitignore beside them for exactly this reason; keep the rest of ./out in a private repository anyway. (Those keys are the one thing not derived from the inputs: --mesh-edge generates them on the first run and reuses them afterwards, so re-running still diffs clean. See The Contract.)

prepare exits 10 if the report still contains MANUAL items and 11 if it contains ASK items, and prints the MANUAL list. The artifacts are written either way — they are the AUTO plus answered-ASK surface and they are correct — but the exit code tells you the migration is not complete.

6. Pre-flight: is the target ready?

export PDNS_API_KEY=… CERTMATE_TOKEN=…
flareover doctor \
  --pdns-url http://pdns:8081 \
  --certmate-url http://certmate:8000 \
  --check-caddy                 # GO / NO-GO: exit 0 only when every target is ready

7. Provision: stand the target up

flareover provision --snapshot zone.snapshot.json --decisions decisions.lock \
  --edge-ip 203.0.113.10 \
  --pdns-url http://pdns:8081 --nameservers ns1.example.eu,ns2.example.eu \
  --certmate-url http://certmate:8000 \
  --certmate-dns cloudflare      # pre-cutover: NS still at the source, so solve DNS-01 there

Swap --pdns-url … for --dns <target> to use a managed DNS backend instead of self-hosting (see DNS Targets). Object storage is a separate step: flareover storage buckets.json --out ./out (see Object Storage).

8. Present: the parity gate

flareover present zone.snapshot.json --after-addr 203.0.113.10:443

Probes the live edge vs the staged edge and diffs status codes, redirects, headers, and body. HARD divergences block the cutover (exit 12); SOFT ones are surfaced for review.

9. Cut over, then guard

The final NS move at your registrar stays an explicit human step; flareover never touches your registrar. Afterwards:

flareover guard --url https://example.com --interval 30s \
  --on-unhealthy "…rollback command…"

guard health-watches the new edge and can trigger rollback/failover.

---

Next: The Contract · CLI Reference · Coverage Matrix