@headup/aws-cdn

Headup Static File CDN

An AWS CDK Construct for creating static file hosts using S3, CloudFront and Edge Lambda.

Features:

• Netlify like _redirects file support
• Remove trailing slashes
• Send strong caching headers where applicable
• Send basic security headers (strict-transport-security, x-xss-protection etc.)
• Support .html extensions eg. /foo will resolve to /foo.html in the S3 Bucket
• Creates an IAM user which can only upload files to the created S3 Bucket to be used with the Headup Export Server
• Completely private S3 Buckets. CloudFront will access the bucket using an Origin Access Identity

Install

npm install @headup/aws-cdn

Lets also install aws-cdk v2 and TypeScript tooling

npm install aws-cdk aws-cdk-lib constructs typescript ts-node

AWS Permissions

You need to have an AWS account configured with enough permissions to manage CloudFormation stacks, IAM, S3 Buckets and Lambda Functions.

Setup

Create src/stacks.ts:

import * as cdk from "@aws-cdk/core";
import { HeadupWebsite } from "@headup/aws-cdn";

class MyStack extends cdk.Stack {
    constructor(scope: cdk.Construct, id: string, props: cdk.StackProps) {
        super(scope, id, props);

        new HeadupWebsite(this, "mywebsite", {
            descriptionName: "My Web Site", // human readable name for various comment and description fields

            // Create alias A record for CloudFront distribution. This is
            // alternative for *.cloudfront.net domain. Use this as the
            // domain CNAME value. Using own domain here allows more flexibility
            // since it can be rerouted if needed.
            aRecordAlias: {
                // Get the id from the AWS Route53 panel
                hostedZoneId: "***",
                zoneName: "valucloud.fi",
                domainName: "customer-example.valucloud.fi",
            },

            // After first deploy you can assign a custom domain to the website
            //     domainNames: ["example.com"],
            // A matching certificate in the certificate manager
            //     certificateArn:
            //         "arn:aws:acm:us-east-1:xxxxxxxxxxxx:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        });
    }
}

const app = new cdk.App();

new MyStack(app, "my-stack", {
    env: { account: "<aws account id>", region: "eu-north-1" },
});

❗️ ❗️ ❗️ ❗️ Note Once you have deployed the stack DO NOT CHANGE the passed id (here mywebsite) because it causes recreation of the CloudFront distribution which means you have update your DNS too.

Create cdk.json

{
    "app": "npx ts-node src/stacks.ts"
}

Deploy

Deploy the stack(s).

npx cdk deploy mywebsite mywebsite-edge-lambda

The edge lambda stack is implicit since Edge Lambdas must be configured to the us-east-1 region and a single stack can be only in one region.

Domain

1. Once deployed find out the domain of the created CloudFront distribution (xxxxxxxxxxxxxx.cloudfront.net) using the AWS Console UI and set it as the CNAME of your domain
2. Request or import a certificate for it using the Certificate Manager to the us-east-1 N. Virginia region
3. Uncomment the cloudFrontDomain option and put in your domain and the ARN of the certificate
4. Run the cdk deploy again

Multiple Websites

You can create multiple instances of the HeadupWebsite construct in your stack.

You can also manually create the IAM user and the Edge Router to share them between the sites:

import { HeadupWebsite, HeadupEdgeRouter } from "@headup/aws-cdn";

class MyStack extends cdk.Stack {
    constructor(scope: cdk.Construct, id: string, props: cdk.StackProps) {
        super(scope, id, props);

        const user = new iam.User(this, "my-shared-user");

        const edgeRouter = new HeadupEdgeRouter(this, "myedge-stack", {
            stackId: "myedge-stack",
        });

        new HeadupWebsite(this, "mywebsite1", { user, edgeRouter });
        new HeadupWebsite(this, "mywebsite2", { user, edgeRouter });
        new HeadupWebsite(this, "mywebsite3", { user, edgeRouter });
    }
}