makestatic-deploy-s3
v1.0.21
Published
Deploy provider for amazon s3
Downloads
25
Readme
Deploy S3
Deploy provider for s3
Deploys build files to amazon s3.
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
.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