DNS in SpipCP: the two layers
The one model that prevents most DNS confusion — delegation (the nameservers, set at the registrar) versus the records (A/CNAME/TXT, inside whoever is authoritative) — then a posture to pick.
Everything network-facing lives in one place: the Networking section. It gathers how domains resolve (DNS), the certificates that secure them (SSL/TLS), and the operator's own nameserver boxes — a single home, a bit like Cloudflare, except the posture is chosen explicitly and nothing is proxied or terminated upstream unless configured to be.
Networking ▸ Domains · Providers · Nameservers · Edge proxy · SSL- Domains — the fleet-wide inventory: one row per hostname, each tagged with its detected authority tier (Hosted / Connected / External). Before anything is attached, this page is the posture chooser + the demarcation matrix.
- Providers — managed provider accounts (the cascade), each showing the zones it holds, plus the switchboard for which providers are offered.
- Nameservers — the operator's own PowerDNS boxes and the self-hosted zone + record editor; each row links across to its Node, and a nameserver node links back here.
- Edge proxy — front an IPv6-only origin with dedicated public-IPv4 edge boxes.
- SSL — the certificate authorities (issuers) that are trusted, custom certificate upload, and the fleet cert-scenario coverage. (Per-domain cert state lives on Domains.)
Who controls the DNS? The three tiers
Every hostname is one of three detected tiers — Hosted (nameservers run here), Connected (a provider account held on the panel's behalf), or External (someone else's DNS). The tier is detected, never picked. See Domains: the three tiers.
The one model below makes the choices make sense, and prevents most DNS confusion.
The two layers
Every domain's DNS is really two separate things stacked on top of each other. Mixing them up is the top cause of "I changed a record and nothing happened."
Layer 1 — delegation: who is authoritative
Set at the registrar, on the domain. It answers "who is authoritative for example.com?" — the
nameservers. Commonly something like *.ns.cloudflare.com; with self-hosted DNS it
becomes ns1.spipdns.com / ns2.spipdns.com. Changing the nameservers moves the whole zone's
authority to a different system. It's not a record swap — it's "move house."
Layer 2 — the records: what the answers are
A / AAAA / CNAME / MX / TXT, and the wildcard. These live inside whoever is currently authoritative (the nameservers from Layer 1). With a managed provider, the panel writes them through that provider's API. Self-hosted, the panel writes them onto each dedicated box. Editing a record never changes who's authoritative — it changes the answers that authority gives.
The rule that follows: a record only takes effect inside the nameservers a domain is currently
delegated to. If example.com is delegated to Cloudflare but the record is added at Bunny, nothing
happens — Bunny isn't authoritative for that domain. Get Layer 1 right first, then Layer 2.
Where each path sits
| Layer 1 (delegation) | Layer 2 (records) | |
|---|---|---|
| Managed provider | Already done — delegation to the provider's nameservers happened when the domain was set up there. SpipCP doesn't touch it. | SpipCP writes them via the provider's API (the DNS account cascade). |
| Self-hosted | SpipCP owns this too — delegation points to ns1/ns2.spipdns.com, which is why it needs the glue wizard and the nameserver boxes. | SpipCP writes them onto each dedicated box. |
A managed provider only touches Layer 2 — delegation was already handled when the domain was pointed at that provider. Self-hosted owns both layers, the extra responsibility (and ownership) of running dedicated nameservers.
Choosing a posture
Every branded subdomain (roadmap.app1.com, *.roadmap.mydomain.com) needs DNS to resolve and a TLS
certificate to serve. Before anything is attached, the Domains page presents
three postures side by side for a knowing choice; once the first hostname is attached it becomes
the fleet inventory. (The TLS half is always Caddy on the serving node — see
the passthrough guarantee.)
In one line:
- Managed provider: least work, but a third party — possibly US-hosted — holds the records. EU options (Bunny, Hetzner, deSEC, Gcore) keep it managed but off US soil.
- Self-hosted: both layers owned end to end — true data ownership — at the cost of running two nameserver boxes.
- Manual (BYO DNS): keep DNS wherever it is today and add the attach record by hand.
The demarcation matrix
The Domains empty state renders this as a live capability matrix per posture — what each one automates. The values are read from each provider's capability contract, never hard-coded:
| Managed provider | Self-hosted nameservers | Manual (BYO DNS) | |
|---|---|---|---|
| Self-service records | ✅ panel writes them via the provider API | ✅ full editor in the panel | ❌ added by hand |
Wildcard cert (*.x) | ✅ DNS-01 automatic | ✅ DNS-01 automatic | ❌ no credential to write the TXT |
| Per-host cert | ✅ HTTP-01 or DNS-01 | ✅ HTTP-01 or DNS-01 | ✅ HTTP-01 only |
| Hands-off onboarding | ✅ fully scriptable | ✅ fully scriptable | ❌ a manual record step |
| Data ownership | provider holds the records | fully self-held | wherever the DNS lives |
Self-hosted is now wildcard-capable too
Self-hosted nameservers used to be limited to per-host (HTTP-01) certificates. They now self-solve the DNS-01 challenge against a dedicated PowerDNS box, so the self-hosted posture earns the same ✅ for wildcards (and full scriptability) as a managed provider — with none of the third-party trust. Both fully-automated columns can drive scripted onboarding end to end.
Where to go next
- Follow a guided checklist → Set up (guided journeys) — pick a posture and let the panel sequence the steps, resumable from the live fleet.
- Pick a managed provider → Managed providers in depth, or the quick setup at Settings → DNS providers.
- Run dedicated nameservers → Self-hosted DNS.
- Understand the certificate matrix → SSL/TLS certificates.
- Attach a domain to a site → Domains & SSL.
- Script onboarding over the API → Domains & Routes API with an API token.
Set up (guided journeys)
The Networking "Set up" surface turns each DNS posture into a resumable checklist whose progress is read from the live fleet — leave for the registrar, come back days later, and it shows exactly where things stand.
Domains: the fleet inventory & the three tiers
One table for every hostname the fleet serves, each tagged with its detected DNS authority — Hosted, Connected, or External. The tier is detected, never picked.