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:

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.
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.

The hostname routes

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

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).

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.

DNS mode 1: Manual DNS (default)

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:

{
  "domain": "app.example.com",
  "dns_mode": "external_records",
  "dns_records": [
    { "record_type": "CNAME", "name": "...", "value": "..." }
  ]
}

Then:

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

Call the finalize route to complete activation:

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

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:

{
  "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.

Retrying when record application fails

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:

{
  "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.

Where to go next

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”.