Domains, DNS, Email & Staging Auth

Status: planned (final cutover step). Do this last, once the verticals are stable. It is the prerequisite for transactional email (Resend) and SMS/voice (Twilio). The domain insigz.com is managed by the owner on GoDaddy. Tracked in the build plan and PROJECT_STATE.

1. Subdomain scheme

2. DNS approach — pick one

Option 1 — delegate DNS to Cloud DNS (recommended for automation)

1. Create a managed zone in project insigz:

   gcloud dns managed-zones create insigz --dns-name=insigz.com. --description="insigz" --project=insigz

2. Read the 4 nameservers:

   gcloud dns managed-zones describe insigz --project=insigz --format="value(nameServers)"

3. In GoDaddy → Domain → Nameservers, switch to "Custom" and enter those 4 NS. Propagation: up to 24–48h.
4. From then on, all records (Cloud Run mappings, Resend) are managed with gcloud dns record-sets ....

Trade-off: DNS editing leaves GoDaddy and lives in GCP.

Option 2 — keep GoDaddy as DNS host

Keep GoDaddy DNS; add the records below in GoDaddy → DNS → Records by hand. More manual, no nameserver change.

3. Cloud Run custom domains

One-time: verify domain ownership (Google gives a TXT record to add). Then map each host:

gcloud beta run domain-mappings create --service=insigz-app        --domain=app.insigz.com     --region=europe-west6 --project=insigz
gcloud beta run domain-mappings create --service=insigz-app-staging --domain=staging.insigz.com --region=europe-west6 --project=insigz
gcloud beta run domain-mappings create --service=insigz-docs        --domain=docs.insigz.com    --region=europe-west6 --project=insigz

Each prints DNS records to add:

• Subdomains (app, staging, docs): a CNAME to ghs.googlehosted.com.
• Apex (insigz.com): A / AAAA records to the Google IPs the mapping returns.

Google-managed TLS provisions automatically (15–60 min). For apex-on-load-balancer or IAP, use a Global External HTTPS Load Balancer with a serverless NEG instead of a direct mapping.

4. Staging password protection

Cloud Run has no built-in basic auth. Add a Next.js middleware in insigz-app that, when the env STAGING_BASIC_AUTH is set (staging service only), requires HTTP Basic auth matching it and returns 401 otherwise. Production leaves the env unset, so there is no gate.

• Secret: insigz-staging-basic-auth (value user:pass), injected on the staging deploy only.
• Alternative: Identity-Aware Proxy (IAP) via a Load Balancer for Google-login gating (heavier).

5. Email — Resend domain verification

To send from @insigz.com (invoices, notifications):

1. Resend → Domains → add insigz.com (or send.insigz.com).
2. Add the records Resend shows to DNS:
   • DKIM: about 3 CNAME records (resend._domainkey...).
   • SPF: a TXT (v=spf1 include:...resend... ~all) or a return-path CNAME.
   • DMARC (recommended): TXT at _dmarc.insigz.com = v=DMARC1; p=none; rua=mailto:....
3. After "Verified", set RESEND_FROM_EMAIL="insigz <noreply@insigz.com>" and RESEND_API_KEY (secrets insigz-resend-api-key-staging / -prod); wire lib/email.ts (adapt MOB/Kiwano).

Twilio (later, for SMS/voice): API keys only (insigz-twilio-* secrets), minimal/no DNS.

6. What the owner must do / access needed

• Claude cannot access GoDaddy. Choose: (a) make the DNS edits yourself, (b) delegate DNS to Cloud DNS (Option 1) so Claude manages records, or (c) provide a GoDaddy API key + secret for Claude to script via the GoDaddy API.
• Confirm the DNS approach, repoint nameservers (Option 1) or paste records (Option 2), and provide the Resend API key when email is wanted.

7. Execution order

1. Verify domain ownership (TXT).
2. Cloud Run domain mappings (app. / staging. / docs. / apex).
3. Add the DNS records (Option 1 or 2).
4. Ship the staging basic-auth middleware.
5. Resend domain verification + wire email.
6. Update NEXT_PUBLIC_SERVER_URL / SERVER_URL / INSIGZ_AI_URL / INSIGZ_APP_URL envs + CI to the new hostnames; redeploy all services.
7. (Later) Twilio.