{"id":"69e6c22f2f5a6f491bc7894f","title":"2026 04 21","path":"how-to/committee/release-notes/2026-04-21","contentMarkdown":"# 21-Apr-2026 — attach custom domains to existing environments [#242](https://github.com/nbarrett/ngx-ramblers/issues/242)\n\n## [build 618](https://github.com/nbarrett/ngx-ramblers/actions/runs/24696664426) — [commit c582a9b](https://github.com/nbarrett/ngx-ramblers/commit/c582a9b793be579eeadc55ae7897c8b200d35842)\n\n_____\n\n- Add first-class Cloudflare + Fly certificate plumbing for attaching an\narbitrary custom domain to an existing environment, exposed as an **Add / Remove Custom Domain** action on the Environment Management Modify\ntab. Cuts out the manual `flyctl certs add` + hand-edited DNS dance\npreviously required per domain cutover.\n- See screenshot below for how custom domain configuration can now be added to the modify stage of environment set up:\n\n![](https://ngx-ramblers.org.uk/api/aws/s3/site-content/98732741-a8ae-4ec3-b112-7f819d45b267.jpeg)\n\n\n\n## Config model\n\n- New `CustomDomainStatus` enum (`pending` / `attached` / `failed`)\nand `CustomDomainEntry` interface (`hostname`, `addedAt`, `status`,\noptional `zoneId` and `message`).\n- `EnvironmentConfig` gains `customDomains?: CustomDomainEntry[]`,\npersisted on the environments config doc under each environment.\n- `ExistingEnvironment` carries the list out to the admin UI.\n- New `CustomDomainResponse` for add/remove API calls.\n\n## Admin UI (Modify tab)\n\n- New \"Custom Domains\" panel on `environment-management.ts` with:\n- Hostname input + Add Custom Domain button (disabled while any\noperation is busy).\n- Per-domain table listing hostname, status badge\n(`attached`/`pending`/`failed`), added-at, and a Remove action.\n- Inline error + scrollable session-log message stream wired through\nthe existing `SessionLogsComponent`.\n- `addCustomDomain` / `removeCustomDomain` client methods on\n`EnvironmentSetupService` hit the new routes.\n- Resetting the Modify tab now also clears the custom-domain scratch\nstate.\n- `ManageAction` enum replaces stringly-typed `'modify'` / `'destroy'`\nvalues across the component.\n- Environment empty-state now renders the \"No environments configured\nyet\" alert unconditionally when the list is empty, instead of showing\na spinner-in-dropdown during the initial fetch.\n\n## Server plumbing\n\n- `server/lib/cli/commands/subdomain.ts` grows two exported functions:\n- `addCustomDomainForEnvironment(envName, hostname)`\n- validates the\nhostname (FQDN, no scheme, no path), loads env config, verifies the\nCloudflare token, resolves the zone via the new `zoneForHostname`,\nensures the Fly app has an IPv4 (allocates a shared one if missing),\nupserts A / AAAA records for the hostname, requests a Fly\ncertificate, reads back the issuance status, and persists a\n`CustomDomainEntry` on the environments config doc regardless of\noutcome so the UI shows `pending` / `attached` / `failed`.\nIdempotent: existing DNS records and certificates are detected and\nskipped.\n- `removeCustomDomainForEnvironment(envName, hostname)`\n- deletes\nmatching DNS records, removes the Fly certificate, and clears the\nentry from the config doc. Tolerant of missing zones and missing Fly\ntokens.\n- Duplicate-hostname guard refuses to attach a hostname already claimed\nby another environment.\n- Admin attach flow auto-updates `group.href` in system config when an\napex custom domain is attached, removing a previously-undiscoverable\nmanual step.\n\n## Cloudflare helpers\n\n- `CloudflareZone` model type (id / name / status).\n- `listZones(apiToken, name?)` and `zoneForHostname(apiToken, hostname)`\nin `cloudflare-dns.ts`: walks the label chain\n(`sub.example.co.uk`, `example.co.uk`, `co.uk`) and resolves the\nfirst zone Cloudflare reports back under that exact name.\n- `CLOUDFLARE_API_BASE` + `cloudflareApi.*` helper centralises all\n`https://api.cloudflare.com/client/v4/...` URL construction; every\ncall site updated.\n\n## MX record handler zone-awareness\n\n- `/cloudflare/email-routing/mx-records` GET and POST handlers now\nresolve the zone for the current `baseDomain` via `zoneForHostname`\nand operate on that zone instead of the default NGX zone. Previously,\ncustom-domain MX state was read from (and written to) the wrong zone,\nproducing false \"Missing MX records\" status and Cloudflare\n\"An identical record already exists\" rejections.\n\n## Routes\n\n- `POST /environment-setup/add-custom-domain/:environmentName` and\n`POST /environment-setup/remove-custom-domain/:environmentName` behind\nthe existing `validateSetupAccess` guard. Errors are surfaced verbatim\nto the client (including `EnvironmentNotFoundError` -> 404) so the\nsession-log panel shows the Cloudflare / Fly reason rather than a\ngeneric 500.\n- `GET /environment-setup/existing-environments` now includes\n`customDomains` on each environment so the UI can render the list.\n\n## Brevo domain authentication automation\n\n- `authenticateSendingDomain` now accepts optional `cloudflareDnsConfig`\nand `baseDomainOverride`, so it can authenticate any domain in any\nzone - not only the NGX default. When no override is passed it\nresolves the correct zone via `zoneForHostname(apiToken, domainName)`\ninstead of defaulting to the configured NGX zone; the previous\ndefault caused DKIM/brevoCode TXT writes to collide in the wrong\nzone.\n- New `ensureDkimAvailable` helper: when Brevo's\n`GET /senders/domains/configuration` returns no DKIM for a registered\ndomain, delete and re-register, then use the `POST /senders/domains`\nresponse body's `dnsRecords` directly (Brevo's own UI's \"Authenticate\nthe domain yourself\" shortcut). Eliminates the manual detour into\n`app.brevo.com` previously required for fresh custom domains.\n- Refactored the inline try/catch `let` ladders in\n`authenticateSendingDomain` into `configureDnsRecords`,\n`requestAuthentication`, and `resolveCfAndBaseDomain` helpers that\nreturn typed results.\n- `brevoDomainsUrl` is now included on every non-authenticated outcome\n(including DNS-failure early returns), not just the \"missing DKIM\"\ncase, so admins always have an escape hatch to Brevo's UI.\n- `brevo/domains/config` route returns `response: null` with HTTP 200\nfor Brevo 404s instead of bubbling an error, so the frontend console\nand `MailService` logger stop spamming on the expected \"not\nregistered yet\" state.\n\n## Brevo sending-domain switch\n\n- New `POST /brevo/domains/switch` route + `switchBrevoSendingDomain`\norchestrator re-authenticate a target domain in Brevo, create the\nDKIM/SPF records in the correct Cloudflare zone, and mass-rewrite\nevery sender from `@oldDomain` to `@newDomain`. Reuses the existing\nsenders helpers (`listBrevoSenders`, `registerBrevoSender`,\n`deleteBrevoSenderById`) - no duplication of Brevo API code.\n- `listBrevoSenders` extracted to a shared helper; `deleteBrevoSenderById`\nexposed for reuse from the switch flow.\n- Mail Senders tab surfaces a warning banner + \"Switch sending domain\nto \" button when the Brevo-authenticated domain differs\nfrom `group.href`. Returned `logs[]` stream through\n`SessionLogsComponent`; on success, `baseDomain`, domain status, MX\nrecords and senders all reload.\n\n## Button-wrapper disabled-state fix\n\n- `` no longer uses Bootstrap's `.disabled` class\n(which applies `pointer-events: none`) to render the disabled state;\nreplaced with a local `is-disabled` opacity-only class. Previously,\nclicks on visually-disabled buttons fell through the wrapper's\n`blockClick` handler and fired the caller's `(click)` binding anyway.\nAffects all 23 `` callers across the app with\n`[disabled]` bindings.\n\n## Subdomain refactors\n\n- `server/lib/cli/commands/subdomain.ts`\n- pulled the two remaining\n`let`-driven if/else ladders in the check flow into\n`reconcileCustomDomainDns` (does DNS reconciliation, returns a\n`dnsProblem | undefined`) and `classifyCertStatus` (pure function\nmapping `cert` + `dnsProblem` to `{ status, message }`).","contentHtml":"

21-Apr-2026 — attach custom domains to existing environments #242

\n

build 618 — commit c582a9b

\n
\n
    \n
  • Add first-class Cloudflare + Fly certificate plumbing for attaching an\narbitrary custom domain to an existing environment, exposed as an Add / Remove Custom Domain action on the Environment Management Modify\ntab. Cuts out the manual flyctl certs add + hand-edited DNS dance\npreviously required per domain cutover.
    • \n
  • See screenshot below for how custom domain configuration can now be added to the modify stage of environment set up:
    • \n
\n

\"\"

\n

Config model

\n
    \n
  • New CustomDomainStatus enum (pending / attached / failed)\nand CustomDomainEntry interface (hostname, addedAt, status,\noptional zoneId and message).
    • \n
  • EnvironmentConfig gains customDomains?: CustomDomainEntry[],\npersisted on the environments config doc under each environment.
    • \n
  • ExistingEnvironment carries the list out to the admin UI.
    • \n
  • New CustomDomainResponse for add/remove API calls.
    • \n
\n

Admin UI (Modify tab)

\n
    \n
  • New "Custom Domains" panel on environment-management.ts with:
    • \n
  • Hostname input + Add Custom Domain button (disabled while any\noperation is busy).
    • \n
  • Per-domain table listing hostname, status badge\n(attached/pending/failed), added-at, and a Remove action.
    • \n
  • Inline error + scrollable session-log message stream wired through\nthe existing SessionLogsComponent.
    • \n
  • addCustomDomain / removeCustomDomain client methods on\nEnvironmentSetupService hit the new routes.
    • \n
  • Resetting the Modify tab now also clears the custom-domain scratch\nstate.
    • \n
  • ManageAction enum replaces stringly-typed 'modify' / 'destroy'\nvalues across the component.
    • \n
  • Environment empty-state now renders the "No environments configured\nyet" alert unconditionally when the list is empty, instead of showing\na spinner-in-dropdown during the initial fetch.
    • \n
\n

Server plumbing

\n
    \n
  • server/lib/cli/commands/subdomain.ts grows two exported functions:
    • \n
  • addCustomDomainForEnvironment(envName, hostname)
    • \n
  • validates the\nhostname (FQDN, no scheme, no path), loads env config, verifies the\nCloudflare token, resolves the zone via the new zoneForHostname,\nensures the Fly app has an IPv4 (allocates a shared one if missing),\nupserts A / AAAA records for the hostname, requests a Fly\ncertificate, reads back the issuance status, and persists a\nCustomDomainEntry on the environments config doc regardless of\noutcome so the UI shows pending / attached / failed.\nIdempotent: existing DNS records and certificates are detected and\nskipped.
    • \n
  • removeCustomDomainForEnvironment(envName, hostname)
    • \n
  • deletes\nmatching DNS records, removes the Fly certificate, and clears the\nentry from the config doc. Tolerant of missing zones and missing Fly\ntokens.
    • \n
  • Duplicate-hostname guard refuses to attach a hostname already claimed\nby another environment.
    • \n
  • Admin attach flow auto-updates group.href in system config when an\napex custom domain is attached, removing a previously-undiscoverable\nmanual step.
    • \n
\n

Cloudflare helpers

\n
    \n
  • CloudflareZone model type (id / name / status).
    • \n
  • listZones(apiToken, name?) and zoneForHostname(apiToken, hostname)\nin cloudflare-dns.ts: walks the label chain\n(sub.example.co.uk, example.co.uk, co.uk) and resolves the\nfirst zone Cloudflare reports back under that exact name.
    • \n
  • CLOUDFLARE_API_BASE + cloudflareApi.* helper centralises all\nhttps://api.cloudflare.com/client/v4/... URL construction; every\ncall site updated.
    • \n
\n

MX record handler zone-awareness

\n
    \n
  • /cloudflare/email-routing/mx-records GET and POST handlers now\nresolve the zone for the current baseDomain via zoneForHostname\nand operate on that zone instead of the default NGX zone. Previously,\ncustom-domain MX state was read from (and written to) the wrong zone,\nproducing false "Missing MX records" status and Cloudflare\n"An identical record already exists" rejections.
    • \n
\n

Routes

\n
    \n
  • POST /environment-setup/add-custom-domain/:environmentName and\nPOST /environment-setup/remove-custom-domain/:environmentName behind\nthe existing validateSetupAccess guard. Errors are surfaced verbatim\nto the client (including EnvironmentNotFoundError -> 404) so the\nsession-log panel shows the Cloudflare / Fly reason rather than a\ngeneric 500.
    • \n
  • GET /environment-setup/existing-environments now includes\ncustomDomains on each environment so the UI can render the list.
    • \n
\n

Brevo domain authentication automation

\n
    \n
  • authenticateSendingDomain now accepts optional cloudflareDnsConfig\nand baseDomainOverride, so it can authenticate any domain in any\nzone - not only the NGX default. When no override is passed it\nresolves the correct zone via zoneForHostname(apiToken, domainName)\ninstead of defaulting to the configured NGX zone; the previous\ndefault caused DKIM/brevoCode TXT writes to collide in the wrong\nzone.
    • \n
  • New ensureDkimAvailable helper: when Brevo's\nGET /senders/domains/configuration returns no DKIM for a registered\ndomain, delete and re-register, then use the POST /senders/domains\nresponse body's dnsRecords directly (Brevo's own UI's "Authenticate\nthe domain yourself" shortcut). Eliminates the manual detour into\napp.brevo.com previously required for fresh custom domains.
    • \n
  • Refactored the inline try/catch let ladders in\nauthenticateSendingDomain into configureDnsRecords,\nrequestAuthentication, and resolveCfAndBaseDomain helpers that\nreturn typed results.
    • \n
  • brevoDomainsUrl is now included on every non-authenticated outcome\n(including DNS-failure early returns), not just the "missing DKIM"\ncase, so admins always have an escape hatch to Brevo's UI.
    • \n
  • brevo/domains/config route returns response: null with HTTP 200\nfor Brevo 404s instead of bubbling an error, so the frontend console\nand MailService logger stop spamming on the expected "not\nregistered yet" state.
    • \n
\n

Brevo sending-domain switch

\n
    \n
  • New POST /brevo/domains/switch route + switchBrevoSendingDomain\norchestrator re-authenticate a target domain in Brevo, create the\nDKIM/SPF records in the correct Cloudflare zone, and mass-rewrite\nevery sender from @oldDomain to @newDomain. Reuses the existing\nsenders helpers (listBrevoSenders, registerBrevoSender,\ndeleteBrevoSenderById) - no duplication of Brevo API code.
    • \n
  • listBrevoSenders extracted to a shared helper; deleteBrevoSenderById\nexposed for reuse from the switch flow.
    • \n
  • Mail Senders tab surfaces a warning banner + "Switch sending domain\nto " button when the Brevo-authenticated domain differs\nfrom group.href. Returned logs[] stream through\nSessionLogsComponent; on success, baseDomain, domain status, MX\nrecords and senders all reload.
    • \n
\n

Button-wrapper disabled-state fix

\n
    \n
  • <app-button-wrapper> no longer uses Bootstrap's .disabled class\n(which applies pointer-events: none) to render the disabled state;\nreplaced with a local is-disabled opacity-only class. Previously,\nclicks on visually-disabled buttons fell through the wrapper's\nblockClick handler and fired the caller's (click) binding anyway.\nAffects all 23 <app-brevo-button> callers across the app with\n[disabled] bindings.
    • \n
\n

Subdomain refactors

\n
    \n
  • server/lib/cli/commands/subdomain.ts
    • \n
  • pulled the two remaining\nlet-driven if/else ladders in the check flow into\nreconcileCustomDomainDns (does DNS reconciliation, returns a\ndnsProblem | undefined) and classifyCertStatus (pure function\nmapping cert + dnsProblem to { status, message }).
    • \n
\n"}