xcloud-shelf

xcloud-shelf demonstrates how to host a static HTML/CSS/JS website on AWS using S3, CloudFront, and Route 53. It also includes a small serverless API and CloudWatch monitoring. All infrastructure is defined with AWS CDK.

Learning goals

• Bucket policy & static website hosting
• SSL/TLS configuration with ACM
• CDN caching behavior
• Route 53 DNS records
• Serverless API with Lambda & API Gateway
• DynamoDB counters
• CloudWatch dashboards and alarms

Project structure

• site/ – static website files
• cdk/ – AWS CDK app that provisions infrastructure

Prerequisites

• Node.js and npm
• An AWS account with the AWS CLI configured
• AWS CDK bootstrapped in the target account/region
• A Route 53 hosted zone for your custom domain (optional)

Usage

Deploy infrastructure and site

cd cdk
npm install        # first-time setup
npm run build
npx cdk bootstrap   # only first time
npx cdk deploy

Custom domain with SSL

Provide domain information via CDK context to automatically request an ACM certificate and create a Route 53 record:

cd cdk
npm run build
npx cdk deploy -c domainName=my.example.com -c hostedZoneId=Z123456789ABC -c hostedZoneName=example.com --profile profile-name

domainName is the full record you want to use, hostedZoneId and hostedZoneName identify the existing Route 53 hosted zone.

Update website content

Modify files under site/ and redeploy to sync with the S3 bucket.

Visitor metrics

A lightweight AWS-backed API (Lambda, API Gateway, and DynamoDB) stores total and active visitor counts. The site calls the API through CloudFront at /api; if the service is unavailable, numbers fall back to "unavailable". Counts update automatically when users load or leave the page.

Monitoring with CloudWatch

The stack enables CloudFront access logging and sets up a CloudWatch dashboard and alarm.

After deployment:

1. In the AWS console, open CloudWatch → Dashboards and select the dashboard named after the stack (e.g. xcloud-shelf-dashboard) to see request counts and error rates.
2. The High5xxErrorRate alarm monitors for 5xx responses. Configure notifications by attaching an SNS topic if desired.
3. Access logs are delivered to the S3 bucket named AccessLogsBucket. You can analyze them with Athena or other tools.

These features provide visibility into site usage and help detect issues quickly.

Development

Run tests:

cd cdk
npm test

To synthesize the CloudFormation template without deploying:

cd cdk
npm run build
npx cdk synth

During development, npx cdk watch can be used to automatically redeploy the stack and sync site assets whenever files change.

Custom domain DNS setup

1. Create a Route 53 hosted zone (via AWS console or CLI).
2. At your domain registrar (e.g. Namecheap), change the nameservers to those from the hosted zone.
3. Wait up to 48 hours for propagation, then verify with nslookup your-domain.com.

Test if in namecheap your domain has update the authorities

dig NS example.com