Custom domain

By default the web apps are served on generated hostnames such as d296tcdmqjm8ho.cloudfront.net. Set DOMAIN_NAME to a Route 53 hosted zone in the same account and the client stack serves them on readable subdomains instead.

Site	Hostname
SaaS app (tenant users)	saas.<zone>
Admin console (system admins)	saas-admin.<zone>
Documentation (this site)	saas-docs.<zone>

The live deployment uses the zone haibui.click, giving saas.haibui.click, saas-admin.haibui.click and saas-docs.haibui.click.

Deploy

DOMAIN_NAME=haibui.click ./scripts/deploy-client.sh

scripts/deploy.sh calls deploy-client.sh at the end, so DOMAIN_NAME=haibui.click ./scripts/deploy.sh you@example.com works too.

Caution

CloudFront only accepts certificates from us-east-1, and the certificate is created in the client stack, so deploy to us-east-1 when using a custom domain.

What gets created

In client/cdk/lib/client-stack.ts:

1. HostedZone.fromLookup finds the zone by name. CDK caches the result in cdk.context.json.
2. One ACM certificate covers all three hostnames, validated with DNS records CDK writes into the zone. The first deploy waits a few minutes for validation.

In client/cdk/lib/static-site.ts, for each site:

3. The CloudFront distribution gets the hostname as an alternate domain name, with the certificate.
4. Route 53 A and AAAA alias records point the hostname at the distribution.

The site’s url, and so the stack outputs AppSiteUrl, AdminSiteUrl and DocsSiteUrl, switch to the custom hostnames.

Nothing else changes

• CORS: the control plane API allows any https:// origin, and the tenant APIs allow *, so the new origins work without a backend change.
• Cognito: both apps sign in with SRP through Amplify, not the hosted UI, so there are no callback URLs to update.
• Old hostnames: the *.cloudfront.net names keep working, so existing bookmarks are fine.

Remove the domain

Deploy again without DOMAIN_NAME. CloudFormation removes the records and the certificate, and the outputs go back to the CloudFront hostnames.