Custom Domains

Point your own domain at a service running on Tawa. The CLI handles DNS, TLS certificates, and ingress configuration automatically.

Add a Domain

Run tawa domain add from your project directory (or pass --service to target a specific service):

tawa domain add mydomain.com

The CLI will ask whether the domain is on InsurEco’s Cloudflare account or managed externally. You can skip the prompt with a flag:

# Auto-configure DNS via Cloudflare
tawa domain add mydomain.com --cloudflare

# Manual DNS — you'll add a CNAME yourself
tawa domain add mydomain.com --external

Option	Description
`--service <name>`	Target service (default: detected from `catalog-info.yaml` or `.tawa.yaml`)
`--env <environment>`	Target environment: `prod` (default), `sandbox`, `uat`
`--cloudflare`	Domain is on InsurEco Cloudflare — DNS is configured automatically
`--external`	Domain uses an external DNS provider — you add the CNAME yourself

Cloudflare-Managed DNS

If the domain is on InsurEco’s Cloudflare, everything is automatic:

tawa domain add portal.example.com --cloudflare

# ✓ DNS record created: portal.example.com → my-svc.tawa.insureco.io
# ✓ Domain registered in platform
# ✓ Domain is live at portal.example.com

A CNAME record is created pointing your domain to the platform hostname. Cloudflare’s Total TLS provisions a certificate automatically. In most cases the domain is live within seconds.

External DNS Provider

If you manage DNS elsewhere (GoDaddy, Namecheap, Route 53, etc.), the CLI tells you exactly what record to add:

tawa domain add portal.example.com --external

# ℹ Please add a CNAME record at your DNS provider:
#
#     portal.example.com  →  my-svc.tawa.insureco.io
#
# ℹ After adding the record, run:
#   tawa domain verify portal.example.com

Add the CNAME at your provider, wait for propagation, then verify:

tawa domain verify portal.example.com

# ✓ DNS verified: portal.example.com → my-svc.tawa.insureco.io

Once verified, deploy to apply the ingress changes:

tawa deploy --prod

Note: DNS propagation can take up to 48 hours, though most providers complete within minutes. You can run tawa domain verify as many times as needed.

Verify & Check Status

Check whether a domain’s DNS has propagated:

tawa domain verify portal.example.com

View full configuration details:

tawa domain status portal.example.com

# Domain:       portal.example.com
# Service:      my-svc
# Environment:  prod
# DNS Provider: cloudflare
# DNS Verified: yes
# DNS Live:     yes
# Resolves To:  my-svc.tawa.insureco.io

List all custom domains (optionally filtered by service):

tawa domain list
tawa domain list --service my-svc
tawa domain list --json

Remove a Domain

tawa domain remove portal.example.com

This removes the DNS record (if Cloudflare-managed), removes the domain from the platform registry, and updates the ingress. Pass --yes to skip the confirmation prompt.

How It Works

When you add a custom domain, the platform:

Creates a CNAME record pointing to your service’s platform hostname (e.g. my-svc.tawa.insureco.io)
Registers the domain in the service registry
Patches the Kubernetes ingress to accept traffic on the new hostname
Provisions a TLS certificate automatically (Cloudflare Total TLS or cert-manager with Let’s Encrypt)

On subsequent deploys, verified custom domains are automatically included in the Helm values so the ingress stays in sync.

Troubleshooting

Symptom	Cause	Fix
`tawa domain verify` says “no CNAME record”	DNS not propagated yet	Wait and retry. Propagation can take up to 48h
Domain resolves but shows a TLS error	Certificate not yet provisioned	Wait a few minutes. Cloudflare/cert-manager provisions certs automatically
Domain resolves to the wrong service	CNAME points to wrong hostname	Check `tawa domain status <domain>` for the expected target and update your DNS
Domain works but stops after redeploy	Domain was not verified before deploy	Run `tawa domain verify <domain>` then redeploy

Getting Started — deploy your first service
catalog-info.yaml Reference — full service configuration options