#Domain Setup

Configuring domains for tsdevstack deployments.

#Overview

All domains route through the load balancer, which directs traffic based on hostname:

#Required Secrets

Before deploying, set the base domain:

npx tsdevstack cloud-secrets:set DOMAIN --value "example.com" --env prod

API_URL and KONG_CORS_ORIGINS are auto-derived during cloud-secrets:push from DOMAIN and the domains configured in .tsdevstack/infrastructure.json -- you do not need to set them manually.

Note: All secrets can also be set directly in your cloud provider's console (GCP Secret Manager, AWS Secrets Manager, Azure Key Vault). The CLI commands are a convenience wrapper.

#Frontend Domains

Configure frontend domains in .tsdevstack/infrastructure.json:

{
  "prod": {
    "frontend": {
      "domain": "example.com"
    },
    "react-app": {
      "domain": "app.example.com"
    }
  }
}

Services are configured directly at the environment level (not nested under a services key).

Backend services (NestJS) don't need domains - they're accessed via Kong.

#Deployment Order

1. Set secrets (DOMAIN — API_URL and KONG_CORS_ORIGINS are auto-derived)
2. Configure domains in infrastructure.json
3. Set up DNS (provider-specific — see below)
4. Deploy infrastructure — npx tsdevstack infra:deploy --env prod
5. Wait for SSL (varies by provider)

#DNS Setup

DNS configuration differs by cloud provider:

Follow your provider's DNS guide:

• GCP DNS & Domains — manual A records + SSL validation CNAMEs at your registrar
• AWS DNS & Domains — move nameservers to Route 53, everything else is automated
• Azure DNS & Domains — move nameservers to Azure DNS, everything else is automated

#Checking Deployment Info

If you need to retrieve deployment details (IPs, DNS records, certificate status) after deployment, check your provider's console:

• GCP: Load Balancing for IP address, Certificate Manager for SSL validation records
• AWS: Route 53 for DNS records, ACM for certificate status, CloudFront for distribution domains
• Azure: DNS zones for nameservers, Front Door for custom domain status and TLS certificates

#Adding a New Domain

To add a new frontend app with its own domain:

1. Add the service to config.json
2. Add domain to .tsdevstack/infrastructure.json:

   {
     "prod": {
       "new-app": {
         "domain": "new.example.com"
       }
     }
   }
3. Deploy the service: npx tsdevstack infra:deploy-service new-app --env prod
4. Update Load Balancer: npx tsdevstack infra:deploy-lb --env prod
5. Add DNS records (A record + SSL validation record)
6. Run npx tsdevstack cloud-secrets:push --env prod to update auto-derived secrets (KONG_CORS_ORIGINS will include the new domain automatically)

#Domain Redirects

To redirect alternate domains (e.g., .app, .io) to your canonical domain, configure redirects in infrastructure.json:

{
  "prod": {
    "loadBalancer": {
      "redirectDomains": ["example.app", "example.io"]
    }
  }
}

All traffic to redirect domains (and their subdomains) will 301 redirect to the canonical domain.

#Troubleshooting

#SSL Certificate Not Provisioning

• GCP: Check that A records and SSL validation CNAMEs are correct at your registrar. Enter relative host names (e.g., api), not full domain names. See GCP DNS & Domains.
• AWS: Check that nameservers at your registrar point to Route 53. Run dig NS example.com +short to verify. See AWS DNS & Domains.
• Azure: Check that nameservers at your registrar point to Azure DNS. See Azure DNS & Domains.

DNS propagation can take up to 48 hours. After fixing DNS, redeploy: npx tsdevstack infra:deploy --env prod

#Wrong Domain Configuration

If you set the wrong domain in secrets or infrastructure.json:

1. Fix the configuration
2. Redeploy: npx tsdevstack infra:deploy --env prod
3. For GCP, update DNS records at your registrar with the new values

#CORS Errors

If frontend apps can't call the API:

1. Verify all frontend domains are configured in .tsdevstack/infrastructure.json -- KONG_CORS_ORIGINS is auto-derived from these entries
2. Re-push secrets to regenerate KONG_CORS_ORIGINS:

   npx tsdevstack cloud-secrets:push --env prod
3. Redeploy Kong:

   npx tsdevstack infra:deploy-kong --env prod