Skip to content
Comwit Cloud

Connect a domain to an app

Once you have deployed a runtime app, you can serve it on your own domain (for example app.example.com instead of the default app URL). Connecting a domain to an app is a two-part job: Comwit asks the runtime (brrrd) to bind the hostname and provision its certificate, and then the right DNS records have to exist so the public internet can find your app.

There are two ways to get those DNS records in place:

  • Automatic DNS (recommended) — the domain is a managed project domain whose DNS Comwit already controls, so Comwit writes the records for you.
  • Manual DNS — the domain’s DNS lives somewhere else, so Comwit hands you the records to publish at your provider yourself.

Both paths attach the hostname to your app and then finalize it. This page walks through each one end to end.

How attaching works

Section titled “How attaching works”

Every hostname you attach goes through the same app domains endpoints:

App hostname API
GET  /v1/projects/{projectId}/apps/{appId}/domains
POST /v1/projects/{projectId}/apps/{appId}/domains
POST /v1/projects/{projectId}/apps/{appId}/domains/{domain}/finalize

Attaching a hostname always calls the runtime control plane first, so brrrd owns the CloudFront certificate and the host-binding lifecycle. The DNS mode you choose in the attach request decides who creates the DNS records.

DNS modeWhen to use itWho writes DNS
managed_project_domainThe hostname is the apex or a subdomain of a managed project domainComwit, into the Route 53 zone
external_records (default)The domain’s DNS is hosted elsewhereYou, at your DNS provider

Path 1 — Automatic DNS (recommended)

Section titled “Path 1 — Automatic DNS (recommended)”

Use this path when the domain is a project domain that Comwit already manages. Comwit writes the required records into the domain’s Route 53 zone for you, including any CloudFront _cf-challenge TXT records, so there is nothing to copy and paste at a registrar.

1. Make sure the project domain is managed

Section titled “1. Make sure the project domain is managed”

Automatic DNS is only available when the hostname is the apex or a subdomain of a project domain whose status is managed. If you have not onboarded the domain yet, follow Bring your own domain first: add the domain, point your registrar’s nameservers at the Comwit zone, and confirm delegation so the domain becomes managed.

2. Attach the app hostname with managed_project_domain

Section titled “2. Attach the app hostname with managed_project_domain”

Attach the hostname and ask Comwit to manage its DNS:

CLI
comwit deploy --project <projectId> --app <appId> --package ./dist \
  --host app.example.com

--host binds the hostname during a deploy. The attach request itself maps to the app domains route:

API
POST /v1/projects/{projectId}/apps/{appId}/domains
Request body
{ "domain": "app.example.com", "dns_mode": "managed_project_domain" }

On success, Comwit creates the records in the project domain’s Route 53 zone and returns the managed-DNS result:

Response
{ "domain": "app.example.com", "dns_mode": "managed_project_domain",
  "managed_dns": { "project_domain": "example.com", "status": "applied", "records": [] } }

These records are owned by Comwit as platform_app records (tagged with owner_resource_type=runtime_app and owner_resource_id={appId}). You will see them when you list the project domain’s records, but your own manual record edits will not overwrite them — see Manage DNS records.

3. Finalize activation

Section titled “3. Finalize activation”

Creating the DNS records is not the last step. Finish activation through the finalize route:

API
POST /v1/projects/{projectId}/apps/{appId}/domains/app.example.com/finalize

Once finalize completes, your app is reachable on app.example.com.

Path 2 — Manual DNS

Section titled “Path 2 — Manual DNS”

Use this path for a domain whose DNS you keep at another provider (your registrar, Cloudflare, or anywhere else). Comwit cannot write into that zone, so it returns the records you need to publish, and you finalize after they are live.

1. Attach the app hostname with external_records

Section titled “1. Attach the app hostname with external_records”

external_records is the default DNS mode, so attaching a hostname this way needs no extra mode flag:

CLI
comwit deploy --project <projectId> --app <appId> --package ./dist \
  --host app.example.com
API
POST /v1/projects/{projectId}/apps/{appId}/domains
Request body
{ "domain": "app.example.com", "dns_mode": "external_records" }

platform-api returns the DNS records you must publish at your own provider:

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

2. Publish the records at your provider

Section titled “2. Publish the records at your provider”

Create each returned record in your DNS provider’s dashboard exactly as given — match the record_type, name, and value. This typically includes a CNAME pointing the hostname at the runtime, plus any validation records needed for the certificate.

3. Finalize activation

Section titled “3. Finalize activation”

When the records are live, complete activation:

API
POST /v1/projects/{projectId}/apps/{appId}/domains/app.example.com/finalize

After finalize succeeds, your app serves on app.example.com.

Check what is attached

Section titled “Check what is attached”

List the hostnames currently bound to an app at any time:

API
GET /v1/projects/{projectId}/apps/{appId}/domains

Which path should I pick?

Section titled “Which path should I pick?”
  • If you want Comwit to handle DNS automatically and you can change your domain’s nameservers, onboard the domain as a project domain and use Automatic DNS. Start at Bring your own domain.
  • If you need to keep your DNS where it is today, use Manual DNS and publish the returned records yourself.
Section titled “Related”