A simple, easy way to deploy static websites to Amazon S3

Features

• Very little understanding of AWS required
• Interactive UI for configuring deployment
• Step-by-step list of what’s happening
• Support for clean URLs (no

  .html

  extensions)
• Support for subdomains
• Use an AWS Profile (named credentials) to authenticate with AWS
• CDN (CloudFront) and HTTPS/TLS support

Installation

Install it globally:

$ npm install --global @static/discharge

Or add it to your application’s

package.json

$ npm install --save-dev @static/discharge

Usage

Authentication

Credentials in file

Configuring AWS credentials can be a bit confusing. After getting your Access Key ID and Secret Access Key from AWS, you should store them in a file at

~/.aws/credentials

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Replace the example keys with your own.

Credentials in environment

Alternatively, if you prefer environment variables or you are running Discharge in an automated environment like a continuous integration/deployment server you can omit the

aws_profile

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Replace the example keys with your own.

Configure

Configuration is done via a

.discharge.json

discharge init

{
  "domain": "anti-pattern.com",
  "build_command": "bundle exec middleman build",
  "upload_directory": "build",
  "index_key": "index.html",
  "error_key": "404.html",
  "cache": 3600,
  "aws_profile": "website-deployment",
  "aws_region": "us-west-1",
  "cdn": true,
  "dns_configured": false
}

Those are most of the configuration options but a complete list is next.

Configuration options

There are no defaults—all configuration options are explicit and must be provided unless marked as optional.

domain

String

The domain name of your website. This will be used as the name of the S3 bucket your website will be uploaded to.

build_command

String

The command that will be executed in the shell to build your static website.

upload_directory

String

The name of the directory that the

build_command

index_key

String

The key of the document to respond with at the root of the website.

index.html

https://example.com

https://example.com/index.html

error_key

String

The key of the document to respond with if the website endpoint responds with a 404 Not Found. For example,

404.html

cache

Number

cache_control

The number of seconds a browser should cache the files of your website for. This is a simplified version of the HTTP

Cache-Control

0

Cache-Control

"no-cache, no-store, must-revalidate"

3600

Cache-Control

"public, max-age=3600"

Be careful about setting too high a cache length. If you do, when a browser caches it, if you then update the content, that browser will not get the updated content unless the user specifically hard-refreshes the page.

When

cdn

s-maxage

cache

s-maxage

max-age

distribute

If you need finer-grained control over the

Cache-Control

cache_control

cache_control

String

A

Cache-Control

cache

The

s-maxage

cache

cdn

redirects

Array

• prefix_match

  String

The URL path prefix to match on. The redirects are matched in order, so if you have two paths with similar parts, like

some/page

some

• destination

  String

The path to redirect to if the

prefix_match

AWS does not allow the

prefix_match

destination

/some/page

If you need finer-grained control over the routing rules, use the

routing_rules

routing_rules

Array

If the

redirects

[
  {
    Redirect: { /* required */
      HostName: "STRING",
      HttpRedirectCode: "STRING",
      Protocol: "http" || "https",
      ReplaceKeyPrefixWith: "STRING",
      ReplaceKeyWith: "STRING"
    },
    Condition: {
      HttpErrorCodeReturnedEquals: "STRING",
      KeyPrefixEquals: "STRING"
    }
  },
  /* more items */
]

The unusual property casing is intentional—the entire configuration will be passed directly through in the HTTP request.

cdn:

Boolean

Set this to

true

discharge distribute

For more information see the

cache

distribute

aws_profile

String

The AWS profile you’ve specified in a credentials file at

~/.aws/credentials

If you only have one set of credentials then specify “default”.

If you want to create a new AWS user with specific permissions/policies for deployment, you can add another profile in the credentials file and specify the custom profile you’ve added.

If you prefer environment variables or you are running Discharge in an automated environment like a continuous integration/deployment server you can omit this configuration option.

aws_region

String

The Amazon S3 region you want to create your website (bucket) in.

dns_configured

Boolean

If you run

discharge init

false

discharge deploy

true

Deploy

After you’ve finished configuring you can run

discharge deploy

If you change your website configuration (

cache

redirects

Clean URLs

Clean URLs are when the

.html

.html

/projects.html

domain.com/projects

When you deploy, two copies of each HTML file will be uploaded: one with the

.html

some-page.html

some-page.html

some-page

https://example.com/some-page.html

https://example.com/some-page

Distribute

After you’ve finished deploying you can run

discharge distribute

A CDN is a caching layer. It can significantly speed up requests for users located geographically farther from where your website is deployed, and sometimes even for users nearby it. In brief, the way a CDN works is you point your DNS to the CDN. When a request comes in, the CDN relays the request to your origin (in this case S3) then takes the response and caches it according to the

Cache-Control

The

Cache-Control

[1]: CDNs can be configured in a lot of different, complex ways. The goal was to abstract away all of that—choose sane defaults and require no configuration. I think this will work for the vast majority of people, but if there’s a specific reason you need more flexibility let me know, and if it’s widely-needed we can add it.

[2]: While CDNs can be configured without TLS, given that TLS certificates are free and we want the entire web to be encrypted, I can’t see any reason to support not using TLS.

.io domains

Verifying the TLS certificate is done via email. AWS will look up the contact information in the WHOIS database for your domain and then send a verification email to the following email addresses:

• Domain registrant
• Technical contact
• Administrative contact
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]

Inexplicably, the .io domain registrar is the only registrar that does not return contact information from the WHOIS database. That means you have to have one of the five common system email addresses set up on a .io domain or you will not receive the TLS certificate verification email.

Subdomains

You can use any domain, subdomain, or combination you like. You just need to configure your DNS appropriately.

If you want to use a naked domain (

domain.com

If you want to use a subdomain like

www.domain.com

blog.domain.com

If you want to use both a naked domain and a subdomain, create an ALIAS and a CNAME record.

If you want to use only a naked domain or a subdomain, but redirect one to the other (like redirect

www.domain.com

domain.com

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/brandonweiss/discharge.

License

The package is available as open source under the terms of the MIT License.