Domain Configuration

Configure your domain settings in the Serverless CMS project to match your Route 53 hosted zone.

Domain Structure

Serverless CMS uses a subdomain-based architecture. All components are accessed via subdomains of your root domain:

Subdomain	Component	Purpose
`admin.{rootDomain}`	Admin Tool	React SPA for managing sites, templates, and pages
`cms-api.{rootDomain}`	CMS API	Authenticated API for CMS operations
`api.{rootDomain}`	Public API	Public API for content delivery and forms
`{siteName}.{rootDomain}`	Published Sites	Published websites (e.g., blog.example.com)

Example Configuration

If your root domain is example.com, the CMS will use:

Admin Tool: https://admin.example.com
CMS API: https://cms-api.example.com
Public API: https://api.example.com
Site "blog": https://blog.example.com
Site "docs": https://docs.example.com

Note: All subdomains are automatically configured during deployment. You only need to specify the root domain in the configuration file.

Update Configuration File

The root domain is configured in src/main/serverless/config.json. Update this file with your domain:

Locate Configuration File

cd /path/to/serverless-cms
nano src/main/serverless/config.json

Update Root Domain

Find the variables section and update the rootDomain value:

{
  "name": "Serverless CMS",
  "application": "uk.co.example.serverless-cms",
  "provider": "aws",
  "profile": "cms-deploy",
  "variables": {
    "rootDomain": "example.com",
    "version": "1.0.0"
  },
  "regions": [
    {
      "region": "global",
      "items": [
        "components/auth-service.json"
      ]
    },
    {
      "region": "eu-west-2",
      "items": [
        "components/admin-tool.json",
        "components/cms-api.json",
        "components/public-api.json",
        "components/cms-functions.json",
        "components/publisher-function.json",
        "components/public-functions.json",
        "components/content-store.json",
        "components/asset-store.json",
        "components/component-store.json",
        "components/publish-store.json"
      ]
    }
  ]
}

Replace "example.com" with your actual domain name.

Verify Component Configurations

The component files reference the ${rootDomain} variable. Verify these are correct:

# Check admin-tool.json
cat src/main/serverless/components/admin-tool.json

You should see:

{
  "type": "website",
  "name": "Admin_Tool",
  "providerSettings": {
    "domain": "admin.${rootDomain}",
    "uploads": [...]
  }
}

Variable Substitution: The ${rootDomain} variable is automatically replaced during deployment. You don't need to manually update component files.

SSL/TLS Certificates

The Serverless Maven Plugin automatically provisions SSL/TLS certificates via AWS Certificate Manager (ACM) for all subdomains.

Certificate Provisioning Process

Request Certificate: Plugin requests a wildcard certificate for *.{rootDomain}
DNS Validation: Plugin creates DNS validation records in Route 53
Automatic Validation: ACM validates domain ownership via DNS
Certificate Issuance: Certificate is issued and attached to CloudFront distributions

Certificate Regions

Certificates are provisioned in two regions:

Region	Purpose
`us-east-1`	Required for CloudFront distributions (global)
`eu-west-2`	For API Gateway custom domains (regional)

Validation Time: Certificate validation typically takes 5-30 minutes. If DNS hasn't fully propagated, validation may take longer (up to 48 hours).

Manual Certificate Verification (Optional)

To check certificate status during deployment:

# List certificates in us-east-1 (CloudFront)
aws acm list-certificates --region us-east-1 --profile cms-deploy

# List certificates in eu-west-2 (API Gateway)
aws acm list-certificates --region eu-west-2 --profile cms-deploy

# Describe specific certificate
aws acm describe-certificate \
  --certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/abc123... \
  --region us-east-1 \
  --profile cms-deploy

Verify DNS Setup

Before deploying, verify your DNS configuration is correct:

Check Hosted Zone

# List hosted zones
aws route53 list-hosted-zones --profile cms-deploy

# Get hosted zone details
aws route53 get-hosted-zone --id /hostedzone/Z1234567890ABC --profile cms-deploy

Verify Nameservers

Ensure your domain is using Route 53 nameservers:

# Check nameservers (requires dig)
dig NS example.com +short

# Alternative using nslookup
nslookup -type=NS example.com

You should see AWS nameservers like:

ns-1234.awsdns-12.org.
ns-5678.awsdns-34.co.uk.
ns-9012.awsdns-56.com.
ns-3456.awsdns-78.net.

Test DNS Resolution

After deployment, test that subdomains resolve correctly:

# Test admin subdomain
dig admin.example.com +short

# Test API subdomain
dig cms-api.example.com +short

# Test public API subdomain
dig api.example.com +short

Note: DNS records are created during deployment. These tests will only work after you've completed the deployment step.

Multiple Environments

For multiple environments (dev, staging, production), you can use different root domains or subdomains:

Option 1: Separate Root Domains

Environment	Root Domain	Admin URL
Development	`dev.example.com`	`admin.dev.example.com`
Staging	`staging.example.com`	`admin.staging.example.com`
Production	`example.com`	`admin.example.com`

Option 2: Environment Prefixes

Environment	Root Domain	Admin URL
Development	`example.com`	`dev-admin.example.com`
Staging	`example.com`	`staging-admin.example.com`
Production	`example.com`	`admin.example.com`

To implement environment prefixes, modify component configurations to include the environment variable.

Configuration Validation

Before deploying, validate your configuration:

# Validate serverless configuration
mvn serverless:validate

# Check for syntax errors
cat src/main/serverless/config.json | jq .

The validation command checks:

JSON syntax is valid
Required fields are present
Component references are correct
AWS profile exists and is configured
Route 53 hosted zone exists for root domain

Configuration Complete! Your domain is now configured. Proceed to Deployment to build and deploy the CMS.