makestatic-deploy-s3 v1.0.21

Deploy S3

Deploy provider for s3

Deploys build files to amazon s3.

• Install
• Configuration
• Amazon S3
  • S3 Configuration
    • Domain
    • Credentials
    • Index Document
    • Error Document
    • Region
    • Prefix
    • CORS
    • Policy
    • Redirects
    • Publish
    • Params
    • Cloudfront
• API
  • S3Provider
    • See Also
    • .validate
    • .deploy
• License

Install

yarn add makestatic-deploy-s3

Configuration

Here is the default configuration:

const defaults = {
  // primary domain name will become the bucket name (required)
  domain: undefined,

  // authentication credentials profile (required)
  // read from the ini file at ~/.aws/credentials
  credentials: {
    profile: undefined
  },

  // index page for the website configuration
  index: 'index.html',

  // error document for the website configuration, eg: 404.html
  error: undefined,

  // region for the bucket(s)
  region: 'us-east-1',

  // directory containing files to upload
  source: 'public',

  // prefix for s3 objects
  prefix: '',

  // cors configuration
  cors: [],

  // configure public read-only permissions for the s3 bucket
  // if you are running behind a cloudfront distribution you may
  // want to set this to `false` so that you site is not accessible
  // over plain http using the amazon s3 website URL
  policy: true,

  // cloudfront configuration
  cloudfront: false,

  // maximum number of retries
  retries: 20,

  // list of domains that should redirect all requests to the main domain
  redirects: [],

  // when set skip creating bucket, policy and redirects just put the files
  publish: false,

  // params to add to objects being uploaded
  // useful for cache control settings
  // default is to cache for a year, you may want
  // to change this for the `stage` environment
  // to something like: `no-store, no-cache, must-revalidate`
  params: {
    CacheControl: 'max-age 31536000',
    // modern browsers don't use this old header
    // but for google pagespeed analysis it helps
    // @see https://developers.google.com/web/fundamentals/performance \
    //    /optimizing-content-efficiency/http-caching
    Expires: '2100-01-01T00:00:00Z'
  }
}

module.exports = defaults

Amazon S3

To configure a deployment for s3 all you need to do is specify a domain and provide authentication credentials. The domain will become the name of the bucket and the credentials profile is used to authenticate using credentials stored in ~/.aws/credentials.

module.exports = {
  deploy: {
    production: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        }
      }
    }
  }
}

Before taking a close look at all the configuration options it is worth knowing what happens when you perform a deployment.

• The bucket is created if it does not exist.
• The bucket policy is given public read permissions.
• The bucket is configured for static website hosting.
• The CORS configuration is set if required.
• The redirect buckets are created if required.
• The website assets are uploaded.

The deployment provider uses a diff of the local and remote files to determine the actions that need to be taken which means that repeat deployments will only upload the files that are new or have changed and will delete remote files that no longer exist locally.

S3 Configuration

This section describes each of the configuration properties.

Domain

The domain field is required and becomes the bucket where your files will be uploaded.

Credentials

The credentials object must include the name of a profile that is used for authentication. The actual credentials are stored in the INI formatted file located at ~/.aws/credentials, for example given the following entry:

[example]
aws_access_key_id = xxxxxxxxxx
aws_secret_access_key = xxxxxxxxxx

You can use the example credentials by setting the profile:

module.exports = {
  deploy: {
    production: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        }
      }
    }
  }
}

Index Document

The index field specifies the name of the file to use for directory requests. The default value is index.html.

Error Document

The error field specifies the name of an error document to use typically for handling 404 requests, the default value is undefined. You may wish to set this to 404.html for pretty page not found errors however be aware that if you are using the prefix option you should also include the prefix here, for example production/404.html.

Region

The region to use when creating bucket(s). The default value is us-east-1.

Prefix

The prefix for bucket objects is particularly useful as it provides a mechanism for versioning and environment segregation. We recommend using this to prefix per environment and then configuring cloudfront with the origin path option.

So if we want to separate our stage and production environments the configuration in the app.stage.js configuration would contain:

module.exports = {
  deploy: {
    stage: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        },
        prefix: 'stage',
        error: 'stage/404.html'
      }
    }
  }
}

And the app.production.js file would use a different prefix:

module.exports = {
  deploy: {
    production: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        },
        prefix: 'production',
        error: 'production/404.html'
      }
    }
  }
}

Notice that we use the same domain in this instance because you would use two cloudfront distributions with origin paths set to /production and /stage and then configure the DNS for example.com and stage.example.com to point to the cloudfront distributions.

If you are not using cloudfront you may find it easier to just use different domains without the prefix option and configure CNAME records for example.com and stage.example.com.

CORS

You can use the cors array option to configure cross origin resource sharing rules. See the cors documentation for more information.

Policy

The policy option is a boolean that determines whether the primary bucket (domain) is given a bucket policy that allows public read access. The default value is true. If you are using a cloudfront distribution you may want to disable this to prevent people from accessing the bucket contents using the s3 endpoint. This is particularly useful if you have a strict requirement to enforce access via SSL.

Redirects

Often you may want to serve content from multiple domains in which case it is convenient to redirect all requests from one (or more) domains to another. You can use the redirects array to list the domains that you want to redirect to the primary domain:

module.exports = {
  deploy: {
    production: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        },
        redirects: [
          'www.example.com'
        ]
      }
    }
  }
}

When redirects are specified a bucket is created for each domain with a website configuration that redirects all requests.

Publish

The publish boolean when enabled will only upload the website content. The default value is false. Once you have performed an initial deployment that has created and configured the bucket set this to true and your deployment will be faster!

Params

The params object allows you to set additional parameters when files are uploaded to the bucket. This is particularly useful for setting cache control behaviour. Note that when parameters are specified here they apply to all objects uploaded to the bucket.

The default value configures CacheControl for one year. See the s3 sdk documentation for more detail.

Cloudfront

The s3 deployment provider supports automatic invalidation of cloudfront distributions. After the files have been uploaded if a cloudfront distribution is configured the deployment provider will create a cloudfront invalidation using only the files that have changed. The distribution field must be specified and is the cloudfront distribution identifier and the invalidate boolean must be set in order to invalidate the distribution.

You can explicitly set an array of invalidation paths using the paths list if you like but it is recommended that you let the deployment provider send only the file paths that have changed. You could use this to invalidate the entire distribution if you wanted.

Note that the authenticated user must have access to the cloudfront API in order to create invalidations.

Be aware that Amazon charges for more than a thousand invalidations per month -- you have been warned.

module.exports = {
  deploy: {
    production: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        },
        cloudfront: {
          distribution: 'XXXXXXXXXX',
          invalidate: true,
          // optionally specify the invalidation paths (not recommended)
          // paths: ['/*']
        }
      }
    }
  }
}

There is a meta data leak by containing the distribution identifier in the application configuration but we do not consider this problematic because an attacker would require your authentication credentials in order to modify the distribution. If your credentials are compromised you have bigger problems.

However, for those that would prefer not to leak this information you can put the distribution identifier in the credentials profile and then reference it using the key field, for example add the distribution identifier to ~/.aws/credentials:

[example]
aws_access_key_id = XXXXXXXXXX
aws_secret_access_key = XXXXXXXXXX
cloudfront_distribution_production = XXXXXXXXXX

And then reference it in the cloudfront configuration:

module.exports = {
  deploy: {
    production: {
      s3: {
        domain: 'example.com',
        credentials: {
          profile: 'example'
        },
        cloudfront: {
          key: 'cloudfront_distribution_production',
          invalidate: true
        }
      }
    }
  }
}

API

S3Provider

Deploys the site to Amazon s3.

See Also

• Deploy Site

.validate

S3Provider.prototype.validate(context, config)

Validates the deployment configuration.

Returns a promise that resolves once all validations pass.

• context Object the processing context.
• config Object the deployment configuration.

.deploy

S3Provider.prototype.deploy(context, config)

Perform the deployment.

This is the function that is called by the deploy-site plugin.

Returns a promise that resolves once deployment is complete.

• context Object the processing context.
• config Object the deployment configuration.

License

MIT

Created by mkdoc on March 12, 2017