Skip to content

Custom hostnames

By default a Comwit Cloud app is reachable at the hostname brrrd assigns it. A custom hostname lets you serve that same app from a name you control — for example app.example.com or your apex example.com — backed by an automatically provisioned CloudFront certificate.

Attaching a hostname is a two-step flow:

  1. Attach the hostname to the app. This always calls brrrd-control first, so brrrd owns the CloudFront certificate and the host-binding lifecycle. The response tells you which DNS records need to exist.
  2. Finalize the hostname once those DNS records are in place, which completes activation.

How you get the DNS records in place depends on which of the two DNS modes applies to your hostname.

A hostname (custom domain) attached to an app lives under that app’s domains collection:

GET /v1/projects/{projectId}/apps/{appId}/domains
POST /v1/projects/{projectId}/apps/{appId}/domains
POST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalize
DELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain}
  • GET .../domains lists the hostnames currently attached to the app.
  • POST .../domains attaches a new hostname (the attach step).
  • POST .../domains/{domain}/finalize completes activation (the finalize step).
  • DELETE .../domains/{domain} removes a hostname from the app.

The same flow is available from the CLI:

CLI
comwit apps domains list --project <projectId> --app <appId>
comwit apps domains add --project <projectId> --app <appId> --domain app.example.com
comwit apps domains add --project <projectId> --app <appId> --domain app.example.com --managed
comwit apps domains finalize --project <projectId> --app <appId> --domain app.example.com
comwit apps domains remove --project <projectId> --app <appId> --domain app.example.com

Whichever DNS mode you end up in, the attach call is always made first and always goes through brrrd-control before any DNS work happens.

This is the default mode, dns_mode: "external_records". Use it when the hostname’s DNS is hosted somewhere Comwit Cloud does not manage — your registrar, another DNS provider, or a zone you administer yourself.

When you attach the hostname, platform-api returns the DNS records you must publish at your own DNS provider:

POST .../apps/{appId}/domains response (manual DNS)
{
"domain": "app.example.com",
"dns_mode": "external_records",
"dns_records": [
{ "record_type": "CNAME", "name": "...", "value": "..." }
]
}

Then:

  1. Publish every record in dns_records at your DNS provider exactly as returned.

  2. Call the finalize route to complete activation:

    POST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalize

DNS mode 2: Automatic DNS (managed project domain)

Section titled “DNS mode 2: Automatic DNS (managed project domain)”

This mode, dns_mode: "managed_project_domain", is available when the hostname is the apex or a subdomain of a managed project domain. (A managed project domain is one whose DNS Comwit Cloud hosts for you in Route 53 — see Connect a domain to an app.)

In this mode you do not publish records yourself. When you attach the hostname, platform-api creates the required records in that domain’s Route 53 zone for you — including any CloudFront _cf-challenge TXT records — and returns:

POST .../apps/{appId}/domains response (automatic DNS)
{
"domain": "app.example.com",
"dns_mode": "managed_project_domain",
"managed_dns": {
"project_domain": "example.com",
"status": "applied",
"records": []
}
}

These automatically created records are owned by the platform as platform_app (with owner_resource_type=runtime_app and owner_resource_id={appId}), so your own manual record edits in the same zone will not overwrite them.

You still complete activation through the finalize route once the records are applied.

It is possible for the brrrd attach to succeed but the Route 53 record application to fail. When that happens you get a 202 response with managed_dns.status: "failed" and a retry message:

202 — managed DNS application failed
{
"domain": "app.example.com",
"dns_mode": "managed_project_domain",
"managed_dns": {
"project_domain": "example.com",
"status": "failed"
}
}

To recover, repeat the exact same attach request. The attach is idempotent, so re-sending it retries the Route 53 record application without creating a duplicate or disturbing the existing brrrd binding. Once managed_dns.status comes back as "applied", proceed to the finalize route as usual.

When a hostname should stop serving an app, remove the app-domain binding:

CLI
comwit apps domains remove --project <projectId> --app <appId> --domain app.example.com
API
DELETE /v1/projects/{projectId}/apps/{appId}/domains/{domain}

For managed_project_domain hostnames, Comwit removes the platform-owned platform_app records from the managed Route 53 zone. For external_records hostnames, remove the DNS records at your external DNS provider after the app binding is gone.

  • Connect a domain to an app — the full, newcomer-friendly walkthrough of attaching a domain to a running app, including how project domains become “managed”.