Deployment

Build and deploy Serverless CMS to AWS using Maven and the Serverless Maven Plugin.

Build Process

The Maven build process orchestrates multiple steps to prepare the CMS for deployment:

Build Steps

1. Admin UI Build: Compiles React application with Vite
2. Lambda Functions: Installs Node.js dependencies and packages functions
3. Component Packaging: Creates ZIP files for default components
4. Artifact Assembly: Prepares deployment artifacts for S3 upload

Run the Build

# Navigate to project directory
cd /path/to/serverless-cms

# Clean previous builds and build project
mvn clean package

Expected output:

[INFO] Scanning for projects...
[INFO] 
[INFO] ----------------< uk.co.example:serverless-cms >-----------------
[INFO] Building Serverless CMS 1.0.0
[INFO] --------------------------------[ pom ]--------------------------
[INFO] 
[INFO] --- exec-maven-plugin:3.1.0:exec (build-admin-ui) @ serverless-cms ---
[INFO] Building Admin UI...
[INFO] vite v5.0.0 building for production...
[INFO] ✓ 1234 modules transformed.
[INFO] dist/index.html                  1.23 kB
[INFO] dist/assets/index-abc123.js    456.78 kB
[INFO] 
[INFO] --- exec-maven-plugin:3.1.0:exec (package-cms-functions) @ serverless-cms ---
[INFO] Packaging cms-functions...
[INFO] 
[INFO] --- exec-maven-plugin:3.1.0:exec (package-publisher-function) @ serverless-cms ---
[INFO] Packaging publisher-function...
[INFO] 
[INFO] --- exec-maven-plugin:3.1.0:exec (package-public-functions) @ serverless-cms ---
[INFO] Packaging public-functions...
[INFO] 
[INFO] BUILD SUCCESS
[INFO] Total time:  2:34 min
[INFO] Finished at: 2024-01-15T10:30:00Z

Deployment Profiles

The project supports multiple deployment profiles for different environments:

Profile	Environment	Lambda Memory	Lambda Timeout	Log Level
dev (default)	Development	512 MB	30 seconds	DEBUG
prod	Production	1024 MB	60 seconds	INFO

Using Profiles

# Build with dev profile (default)
mvn clean package

# Build with production profile
mvn clean package -Pprod

Deployment Commands

Validate Configuration

Before deploying, validate your configuration:

mvn serverless:validate

This checks:

• Configuration file syntax
• AWS credentials and profile
• Route 53 hosted zone exists
• Required permissions
• Component references

Preview Changes (Dry Run)

Preview what will be created/updated without making changes:

mvn serverless:plan

Output shows:

• Resources to be created
• Resources to be updated
• Resources to be deleted
• Estimated costs

Deploy to AWS

Deploy the CMS to AWS:

# Deploy with dev profile (default)
mvn serverless:deploy

# Deploy with production profile
mvn serverless:deploy -Pprod

Deployment Progress

During deployment, you'll see progress for each component:

[INFO] --- serverless-maven-plugin:1.0.0:deploy @ serverless-cms ---
[INFO] Deploying Serverless CMS to AWS...
[INFO] 
[INFO] Region: global
[INFO]   ✓ Auth_Service (Cognito User Pool) - Created
[INFO]   ✓ User Pool Client - Created
[INFO]   ✓ Admin user created: george.taylor@taylor-made-software.co.uk
[INFO] 
[INFO] Region: eu-west-2
[INFO]   ✓ Content_Store (DynamoDB) - Created
[INFO]   ✓ Component_Store (S3) - Created
[INFO]   ✓ Asset_Store (S3) - Created
[INFO]   ✓ Publish_Store (S3) - Created
[INFO]   ⏳ Admin_Tool (CloudFront) - Creating distribution...
[INFO]   ⏳ SSL Certificate (ACM) - Validating...
[INFO]   ✓ SSL Certificate - Validated
[INFO]   ✓ Admin_Tool - Deployed
[INFO]   ✓ CMS_API (API Gateway) - Created
[INFO]   ✓ Public_API (API Gateway) - Created
[INFO]   ✓ cms-functions (Lambda) - Deployed
[INFO]   ✓ publisher-function (Lambda) - Deployed
[INFO]   ✓ public-functions (Lambda) - Deployed
[INFO]   ✓ DNS Records (Route 53) - Created
[INFO] 
[INFO] Deployment Summary:
[INFO]   Admin Tool: https://admin.example.com
[INFO]   CMS API: https://cms-api.example.com
[INFO]   Public API: https://api.example.com
[INFO] 
[INFO] BUILD SUCCESS
[INFO] Total time: 18:45 min

Deployment Verification

Verify Deployment Status

mvn serverless:verify

This command checks:

• All resources are created
• CloudFront distributions are deployed
• Lambda functions are active
• API Gateway endpoints are accessible
• DNS records are configured

Manual Verification

Verify each component manually:

1. Check CloudFront Distributions

aws cloudfront list-distributions \
  --query "DistributionList.Items[?Comment=='Admin_Tool'].{Id:Id,Domain:DomainName,Status:Status}" \
  --profile cms-deploy

2. Check Lambda Functions

aws lambda list-functions \
  --query "Functions[?contains(FunctionName, 'serverless-cms')].{Name:FunctionName,Runtime:Runtime,Status:State}" \
  --region eu-west-2 \
  --profile cms-deploy

3. Check DynamoDB Tables

aws dynamodb list-tables \
  --query "TableNames[?contains(@, 'serverless-cms')]" \
  --region eu-west-2 \
  --profile cms-deploy

4. Check S3 Buckets

aws s3 ls --profile cms-deploy | grep serverless-cms

5. Check API Gateway

aws apigatewayv2 get-apis \
  --query "Items[?contains(Name, 'serverless-cms')].{Name:Name,Endpoint:ApiEndpoint}" \
  --region eu-west-2 \
  --profile cms-deploy

Post-Deployment Checks

Test Admin Tool Access

Open the Admin Tool in your browser:

open https://admin.example.com
# Or on Linux:
xdg-open https://admin.example.com

You should see the Serverless CMS login page.

Test API Endpoints

Test the Public API health endpoint:

curl https://api.example.com/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00Z"
}

Check CloudWatch Logs

Verify Lambda functions are logging correctly:

# List log groups
aws logs describe-log-groups \
  --log-group-name-prefix "/aws/lambda/serverless-cms" \
  --region eu-west-2 \
  --profile cms-deploy

# View recent logs for a function
aws logs tail /aws/lambda/serverless-cms-cms-functions-auth-refresh \
  --follow \
  --region eu-west-2 \
  --profile cms-deploy

Verify DNS Resolution

Check that all subdomains resolve correctly:

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

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

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

Updating an Existing Deployment

To update an existing deployment with code changes:

# Rebuild project
mvn clean package

# Preview changes
mvn serverless:plan

# Deploy updates
mvn serverless:deploy

The plugin performs incremental updates:

• Lambda functions are updated with new code
• Admin UI is re-uploaded to S3
• CloudFront cache is invalidated
• Unchanged resources are not modified

Rollback

If deployment fails or you need to rollback:

Rollback to Previous Version

# List deployment history
mvn serverless:history

# Rollback to previous version
mvn serverless:rollback -Dversion=previous

# Rollback to specific version
mvn serverless:rollback -Dversion=1.0.0

Complete Teardown

To completely remove the deployment:

mvn serverless:undeploy

Troubleshooting Deployment Issues

Common deployment issues and solutions:

Certificate Validation Timeout

If SSL certificate validation times out:

• Verify DNS nameservers are correctly configured
• Wait for DNS propagation (up to 48 hours)
• Check Route 53 hosted zone has correct NS records

Permission Denied Errors

If you see permission errors:

• Verify IAM user has all required policies attached
• Check AWS CLI profile is configured correctly
• Ensure profile name matches config.json

CloudFront Distribution Creation Fails

If CloudFront distribution creation fails:

• Check S3 bucket was created successfully
• Verify certificate is in us-east-1 region
• Ensure domain name doesn't conflict with existing distribution

For more troubleshooting help, see the Troubleshooting Guide.