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

tawa domain add mydomain.com

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

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

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 and Cloudflare's Total TLS provisions a certificate automatically. The domain is live within seconds.

External DNS Provider

If you manage DNS elsewhere (GoDaddy, Route 53, etc.):

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
tawa deploy --prod   # apply ingress changes

DNS propagation can take up to 48 hours, though most providers complete within minutes.

Manage Domains

# Check DNS propagation status
tawa domain verify portal.example.com

# View full configuration details
tawa domain status portal.example.com

# List all custom domains
tawa domain list
tawa domain list --service my-svc

# Remove a domain
tawa domain remove portal.example.com

How It Works

When you add a custom domain, the platform:

1. Creates a CNAME record pointing to your service's platform hostname
2. Registers the domain in the service registry
3. Patches the Kubernetes ingress to accept traffic on the new hostname
4. Provisions a TLS certificate automatically (Cloudflare Total TLS or cert-manager)

On subsequent deploys, verified custom domains are automatically included in the Helm values.

Critical Rules — Do NOT Bypass Tawa

IMPORTANT: These rules exist because bypassing Tawa for domain management causes 502/522 errors and broken routing. Learn from past mistakes.

Never manually create DNS CNAMEs for Tawa services

Do NOT use iec-cf:create_dns_record or the Cloudflare dashboard to create CNAME records pointing to *.tawa.pro or *.tawa.insureco.io. The platform will not know about the domain and will return 502/522 errors.

Wrong:

# ❌ NEVER DO THIS — creates DNS but platform doesn't know about the domain
iec-cf:create_dns_record CNAME @ → policyeco-web.tawa.pro
# Result: 502/522 because ingress doesn't accept traffic for this hostname

Right:

# ✅ ALWAYS USE TAWA CLI — handles DNS + platform registration + ingress
tawa domain add mydomain.com --cloudflare

Never use Cloudflare Pages or Wrangler for Tawa services

If a service runs on Tawa, do NOT deploy it to Cloudflare Pages or use wrangler for custom domains. Tawa handles deployment, SSL, DNS, and ingress. Mixing platforms causes conflicts.

Wrong:

# ❌ NEVER DO THIS for a Tawa service
npx wrangler pages deploy dist
npx wrangler pages project create my-svc
# Then manually adding custom domains in CF Pages dashboard

Right:

# ✅ Deploy via Tawa
tawa deploy --prod
# ✅ Add domains via Tawa
tawa domain add mydomain.com --cloudflare

Never use wrangler secret for Tawa services

Secrets for Tawa services are managed via tawa secret set, not wrangler secret put. Wrangler secrets only apply to Cloudflare Workers — they are invisible to Tawa pods.

Wrong:

# ❌ This sets a secret on a CF Worker, NOT on your Tawa service
npx wrangler secret put MY_SECRET

Right:

# ✅ This sets a secret on your Tawa service pod
tawa secret set MY_SECRET

The correct workflow for multi-domain services

For services like PolicyEco that serve 30+ domains from one app:

# 1. Deploy the service first
tawa deploy --prod

# 2. Register domains (one at a time, or batch in a script)
tawa domain add policyeco.io --cloudflare
tawa domain add policybench.io --cloudflare
tawa domain add policyclaim.io --cloudflare
# ... repeat for each domain

# 3. Redeploy to pick up all registered domains in ingress
tawa deploy --prod

# 4. Your Express/Next.js app reads req.hostname to serve the right page

The service must already exist before adding domains. If tawa domain add says "Service not found", deploy first.

If you accidentally create a manual CNAME

1. Delete the CNAME via iec-cf:delete_dns_record
2. Run tawa domain add <domain> --cloudflare to do it properly
3. Run tawa deploy --prod to update ingress

Troubleshooting