Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scaffold-sh/aws-static-website

This infrastructure uses AWS S3 to host a static website in a serverless way.
https://github.com/scaffold-sh/aws-static-website

aws cloudfront codebuild codepipeline s3 scaffold

Last synced: 3 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/scaffold-sh/aws-static-website
Owner: scaffold-sh
License: mit
Created: 2020-09-20T20:18:53.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2020-10-11T08:13:42.000Z (about 4 years ago)
Last Synced: 2024-07-05T16:38:34.802Z (4 months ago)
Topics: aws, cloudfront, codebuild, codepipeline, s3, scaffold
Language: TypeScript
Homepage: https://scaffold.sh/docs/infrastructures/aws/static-website
Size: 163 KB
Stars: 20
Watchers: 3
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

AWS

AWS Static Website

Documentation |
Website |
Blog |
Twitter |
LinkedIn

+ $1.5 / month ~ 4min / create

```console
$ scaffold aws:static-website
```

This infrastructure uses the static website hosting capabilities of **[AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html)** to host your static website in a **serverless way**.

Your **GitHub account** will be connected to **[CodePipeline](https://aws.amazon.com/codepipeline)** and **[CodeBuild](https://aws.amazon.com/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](https://aws.amazon.com/cloudfront)** coupled with **[ACM](https://aws.amazon.com/acm)** to add a fully-managed SSL certificate to your website.

To use an ACM certificate with Amazon CloudFront, the certificate [must be requested](https://docs.aws.amazon.com/acm/latest/userguide/acm-regions.html) in the US East (N. Virginia) region.

This infrastructure also uses **[SSM Parameters Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)** to store your build environment variables.

![](/assets/schema.png)

### 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](https://console.aws.amazon.com/acm/home?region=us-east-1#/) 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](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/acm_certificate_validation) to learn more.

### How do I customize the build stage of my pipeline?

[CodeBuild uses a YAML file](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) to describe all the steps that a stage requires. This file is located in the templates directory at the root of your infrastructure:

```env
# ./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
# .env
BUILD_TOKEN=
```

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

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

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

```yaml
# 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.