/aws-static-website

This infrastructure uses AWS S3 to host a static website in a serverless way.

Primary LanguageTypeScriptMIT LicenseMIT

AWS

AWS Static Website

Documentation | Website | Blog | Twitter | LinkedIn

+ $1.5 / month      ~ 4min / create

Node version Yarn version AWS version Terraform version CDKTF version License 

$ scaffold aws:static-website

This infrastructure uses the static website hosting capabilities of AWS S3 to host your static website in a serverless way.

Your GitHub account will be connected to CodePipeline and CodeBuild, so you will be able to build, test and deploy your favorite SPA and SSG frameworks (React JS, Vue JS, Gatsby JS, Hugo...) using the usual git push command.

Given that the S3 website endpoints do not support HTTPS, this infrastructure uses CloudFront coupled with ACM to add a fully-managed SSL certificate to your website.

To use an ACM certificate with Amazon CloudFront, the certificate must be requested in the US East (N. Virginia) region.

This infrastructure also uses SSM Parameters Store to store your build environment variables.

Requirements

  • You will need a GitHub account to create this infrastructure. Support for GitLab and BitBucket is coming soon.

  • If you plan to use an apex domain for your website (i.e. a root domain that does not contain a subdomain), make sure that your domain host support the ANAME, ALIAS or naked CNAME DNS record type.

Components

Name Source Price
S3 (one bucket)
S3 will be used to store your website source code.		 src/lib/constructs/staticWebsite/bucket.ts Usage
Cloudfront (one distribution)
CloudFront will be used to serve your website from your S3 bucket.		 src/lib/constructs/staticWebsite/cdn.ts Usage
CodePipeline (one pipeline)
CodePipeline will be used to manage the deployments of your website.		 src/lib/constructs/continuousDeployment/pipeline.ts $1 / month
CodeBuild (one build project)
CodeBuild will be used to run the builds of your website.		 src/lib/constructs/continuousDeployment/build.ts +$0.5 / month
ACM (one certificate)
ACM will be used to manage the SSL certificate of your website.		 src/lib/constructs/staticWebsite/ssl.ts Free
SSM (one parameter store)
SSM Parameter Store will be used to store the environment variables of your builds.		 src/lib/constructs/computing/environmentVariables.ts Usage

Environment variables

These environment variables will be automatically configured each time you create an environment (or a sandbox) for your infrastructure.

Name Description
BUILD_COMMAND The command that needs to be run to build your website (e.g. npm i && npm run build) (optional).
BUILD_OUTPUT_DIR The directory where the build command output your website (e.g. build/) (optional).
DOMAIN_NAMES The domain name(s) that you want to use for your website.
ENABLE_HTTPS We need to wait for the ACM certificate to be "issued" to enable HTTPS. See the "after install" section to learn more.
GITHUB_BRANCH The branch from which you want to deploy.
GITHUB_OAUTH_TOKEN The GitHub OAuth token that will be used by CodePipeline to pull your source code from your repository.
GITHUB_REPO The GitHub repository that contains your source code.
GITHUB_REPO_OWNER The owner of your GitHub repository. Can be a regular user or an organization.
GITHUB_WEBHOOK_TOKEN A random token that will be used by CodePipeline and GitHub to prevent impersonation.

Inherited

Name Description
SCAFFOLD_AWS_PROFILE The AWS named profile used to create your infrastructure.
SCAFFOLD_AWS_REGION The AWS region where you want to create your infrastructure.
SCAFFOLD_AWS_S3_BACKEND_BUCKET The AWS S3 bucket that will contain the Terraform state of your infrastructure.
SCAFFOLD_AWS_S3_BACKEND_DYNAMODB_TABLE The AWS DynamoDB table that will be used to store the Terraform state locks.
SCAFFOLD_AWS_S3_BACKEND_KEY The S3 bucket key under which your Terraform state will be saved.
SCAFFOLD_RESOURCE_NAMES_PREFIX An unique custom prefix used to avoid name colision with existing resources.

After install

CloudFront will display a placeholder index file until the end of the first deployment.

This infrastructure exports three Terraform outputs: cloudfront_distribution_uri, pipeline_execution_details_url and ssl_validation_dns_records.

The cloudfront_distribution_uri output value contains the URI of your CloudFront distribution. You could use it to access your website while your DNS are propagating.

The pipeline_execution_details_url output values contains the URL of your pipeline executions details.

The ssl_validation_dns_records output value contains the DNS records that you need to set in order to validate your ACM certificate (see below).

How do I set up my domain name?

The way you will set up your domain name will vary according to the presence or absence of a subdomain.

If your domain name doesn't have any subdomains, you will need to add two DNS records:

  • Name: or @
  • Type: ALIASE, ANAME or CNAME
  • Value: cloudfront_distribution_uri

  • Name: www
  • Type: CNAME
  • Value: cloudfront_distribution_uri

If your domain name has a subdomain, you will need to add one CNAME record:

  • Name: subdomain
  • Type: CNAME
  • Value: cloudfront_distribution_uri

How do I set up HTTPS?

The ssl_validation_dns_records output value contains the DNS records that you need to set in order to validate your ACM certificate.

Once set, you will need to wait for the status of your certificate to switch from "pending" to "issued" to use it with your application load balancer.

You could then set the ENABLE_HTTPS environment variable to "true" in your local env file and run the scaffold apply command to update your infrastructure.

If you want to automate this process, you could use AWS Route 53 as your domain host then use the aws_route53_record and aws_acm_certificate_validation resources to wait for certificate validation. See the Terraform documentation to learn more.

How do I customize the build stage of my pipeline?

CodeBuild uses a YAML file to describe all the steps that a stage requires. This file is located in the templates directory at the root of your infrastructure:

# ./templates                                  
buildspec.yml

You could update this file directly to customize your pipeline build stage.

How do I add environment variables to the build stage?

To add an environment variable to the build stage all you have to do is to add an environment variable that starts with BUILD_ to your infrastructure code.

For example, let's say that you want to add a TOKEN variable to your build. You will first add it to your .env file:

# .env
BUILD_TOKEN=

Then, given that this value is secret you choose to define it in your local env file:

# .env.{environment}.local
BUILD_TOKEN=MY_SECRET_TOKEN

One done, you could access your environment variables in all your buildspec file:

# templates/buildspec.yml

version: 0.2

phases:
  pre_build:
    commands:
      - echo $TOKEN

Remember to run the scaffold apply command each time you update your infrastructure code.