Custom domains & DNS

Every web app gets a production hostname automatically. start_project derives <app>-<org>.<platform-base> and attaches it with TLS, no DNS work from the user. A custom domain is a hostname the user owns (e.g. www.acme.com, acme.com) that you additionally point at the app. This guide is what to tell the user, and in what order.

A custom domain needs two things from the domain's owner: a one-time ownership proof (a DNS TXT record) and a DNS record pointing the host at DeployMill's ingress. DeployMill then issues the TLS certificate itself. The user never supplies a cert.

How the attach flow works

Both attach paths (attach_domain and domains.custom + reconcile_project) run the same validation and surface the same codes, each carrying the exact DNS record to create, so you don't have to know the records up front. The expected, recoverable preconditions come back as a success-shaped result you branch on, not on the error channel:

• attach_domain returns { ok: false, code, reason, ...fields }: the txtRecord for domain_verification_required, the expected/observed for dns_not_pointed, the host for the rest. On success it returns { ok: true, domainId, host, port, url }.
• reconcile_project collects the same failures as { host, code, reason } into plan.domains.blocked[].

The loop is: attach → read the { ok: false, code, ... } result → relay the exact record it carries → the user creates it → retry. The checks are idempotent and run in order (ownership before DNS-reachability).

What the user has to do (the short version)

1. Prove ownership: publish the TXT record from the domain_verification_required result. One-time per org + host.
2. Point the host at the ingress: a CNAME (subdomain) or A record (apex) to the target from the dns_not_pointed result. Must be DNS-only / unproxied.
3. Re-attach: DeployMill issues a Let's Encrypt cert and the host goes live over HTTPS.

Choosing an attach path

Config-as-code (preferred). Add the host to domains.custom in .deploymill/project.json, commit, and run reconcile_project. A host that fails validation is reported in plan.domains.blocked[] ({ host, code, reason }) and skipped. The rest of the reconcile still applies, so fix the record and re-run. Because the host lives in the file it's re-attached on every reconcile (survives drift). Remove it from the list and reconcile with prune: true to detach. See deploymill://guides/project-config.

One-off (attach_domain). Call attach_domain({ applicationId, host, port }). Same validation, but it returns the coded failure directly as { ok: false, code, ... } instead of collecting into blocked. Good for a quick attach, but a host that is not also in domains.custom will be left as-is by future reconciles, and a host that is in the file gets re-added on the next reconcile regardless.

Step 1: ownership proof (domain_verification_required)

The first time your org attaches a given host, the attach returns { ok: false } with code domain_verification_required carrying the record to publish:

{ "ok": false,
  "code": "domain_verification_required",
  "host": "www.acme.com",
  "txtRecord": {
    "type": "TXT",
    "name": "_deploymill-challenge.www.acme.com",
    "value": "deploymill-domain-verification=<token>"
  } }

Tell the user to create exactly that TXT record at their DNS provider, then retry the attach. Notes:

• The token is org-scoped. Proving ownership for one org's token does not authorize a different org to attach the same host.
• Once proven, the (host, org) pair is remembered; later re-attaches (and reconciles) skip this step.
• The record can be removed after the attach succeeds. It's only read at verification time.
• It has to be visible to DeployMill's resolver before the retry; if it was just published, allow for DNS propagation and retry.

Step 2: point DNS at the ingress (dns_not_pointed)

Once ownership is proven, the attach checks that the host actually resolves to DeployMill's ingress. The Let's Encrypt HTTP-01 challenge fails silently otherwise, so no cert would issue. If it isn't pointed yet, the attach fails with the exact target to use:

{ "ok": false,
  "code": "dns_not_pointed",
  "host": "www.acme.com",
  "expected": { "type": "CNAME", "value": "<ingress-host>" },
  "observed": ["A 203.0.113.7"] }

Tell the user to create the record pointing at expected.value:

• Subdomain (www.acme.com, api.acme.com) → a CNAME to expected.value.
• Apex / root (acme.com) → most DNS providers support CNAME-flattening via ALIAS or ANAME records. Use one of those pointed at expected.value. Do not use a bare A record with an IP address, because if the ingress IP ever changes, the domain breaks silently. Standard CNAME at the zone apex is not valid DNS, but every major provider (Cloudflare, Route 53, DNSimple, Namecheap) offers an equivalent flattened record type that follows the hostname instead of pinning an IP.

The record must be DNS-only / unproxied. DeployMill issues the cert via an HTTP-01 challenge that has to reach its origin directly. If the record sits behind the user's own Cloudflare/CDN proxy (the orange cloud in Cloudflare), the proxy intercepts the challenge and no cert issues. Point it straight at the ingress host the error reports, grey-clouded / DNS-only.

skipDnsCheck: true bypasses this pre-check only. Use it when a stale resolver is failing the check but you know DNS is correct. It does not bypass ownership proof, and Let's Encrypt issuance still fails later if DNS truly isn't pointed.

Step 3: the certificate (automatic)

There is no cert step for the user. Once the host is verified and pointed, DeployMill registers it with TLS and the ingress issues a per-host Let's Encrypt certificate over HTTP-01 from DeployMill's origin. Each custom host gets its own cert under the user's domain's Let's Encrypt budget, so this scales across tenants.

Issuance is not instant. After a successful attach, the cert may take a short while to issue and the DNS change to propagate. Don't report the domain "live" off the attach return alone. Confirm by fetching https://<host> (or get_app's health block once the prod URL answers). A freshly attached host may briefly serve a cert warning until issuance completes.

Error codes

Every code below is machine-readable on the tool result. On attach_domain it rides the success-shaped { ok: false, code, ... } payload (the expected, recoverable preconditions), or in plan.domains.blocked[].code for reconcile. Branch on it, don't parse the message. (A genuine infra fault, e.g. the ingress being unreachable, still surfaces on the error channel, not as { ok: false }.)

Detaching

• One-off: detach_domain({ applicationId, host }) (or domainId). Idempotent. Returns { detached: false } if nothing matched.
• Config: remove the host from domains.custom and run reconcile_project with prune: true. A host left in the file is re-added on the next reconcile, so remove it from the file too.

Detaching does not revoke the ownership proof. Re-attaching the same host later for the same org skips re-verification.

What NOT to do

• Don't tell the user to upload or buy a TLS certificate. DeployMill issues it; the only user action is DNS.
• Don't leave the record proxied. An orange-clouded Cloudflare record (or any CDN in front) breaks HTTP-01. The cert never issues. DNS-only.
• Don't use an A record with an IP address. If the ingress IP changes, the domain breaks silently. Always use a CNAME (subdomain) or ALIAS/ANAME (apex) pointed at the ingress hostname so it tracks automatically.
• Don't attach a host under the platform wildcard base — or any platform-owned domain — as a "custom" domain. That's DeployMill's namespace (reserved_hostname, which also covers the platform's reserved apex/marketing domains); the auto-derived prod host is already managed for you.
• Don't report success off the attach return. Verify HTTPS actually serves the app before telling the user it's done.