@evokegroup/aws-deployment
Provides AWS deployments via JSON configuration files. JSON with comments is supported when the file extension is .jsonc
. Settings in the format ${VARIABLE_NAME}
will be replaced with the environment variable value.
// config.json
{
"settings": {
"cloudFront": {
"id": "${CLOUDFRONT_DISTRIBUTION_ID}"
},
"s3": {
"bucket": "${S3_BUCKET_NAME}"
}
},
"deployment": {
"steps": {
"s3.uploadFiles": {
"directory": "static/dist",
"ignore": [
"^.*\\.htaccess$"
]
},
"s3.redirects": {
"redirects": "aws-redirects.jsonc"
},
"s3.redirectionRules": {
"rules": "aws-redirection-rules.json"
},
"cloudFront.invalidate": {},
"s3.removeNotDeployed": {}
}
}
}
const awsDeploy = require('@evokegroup/aws-deployment');
awsDeploy({
config: 'config.json'
})
.then(() => {
// done
})
.catch((err) => {
// error
});
The deployment can perform the same step multiple times by setting deployment.steps
to an Array<object>
.
// config.json
{
"deployment": {
"steps": [{
"s3.uploadFiles": {
"bucket": "${S3_BUCKET_ENGLISH}",
"directory": "static/dist",
"ignore": [
"^fr\\/.*$"
]
}
}, {
"s3.uploadFiles": {
"bucket": "${S3_BUCKET_FRENCH}",
"directory": "static/dist/fr"
}
}]
}
}
Settings: CloudFront
Property | Type | Default | Description |
---|---|---|---|
id | string |
${CLOUDFRONT_DISTRIBUTION_ID} |
The CloudFront distribution ID or environment variable name as ${ENV_VAR_NAME} |
paths | Array<string> |
["/*"] |
The invalidation paths |
{
"settings": {
"cloudFront": {
"id": "ABC123"
}
}
}
{
"settings": {
"cloudFront": {
"id": "${CLOUDFRONT_ID}"
}
}
}
## Settings: S3
| Property | Type | Default | Description |
| -------- | ---- | ------- | ----------- |
| bucket | `string` | `${S3_BUCKET_NAME}` | The S3 bucket name or environment variable name as ${ENV_VAR_NAME} |
```json
{
"settings": {
"s3": {
"bucket": "bucket-name",
}
}
}
{
"settings": {
"s3": {
"bucket": "${S3_BUCKET_NAME}",
}
}
}
Deployment Step: All Steps
Property | Type | Default | Description |
---|---|---|---|
enabled | boolean |
true |
Is the step enabled |
{
"deployment": {
"steps": {
"step.name": {
"enabled": true
}
}
}
}
Deployment Step: cloudFront.invalidate
Invalidates paths within a CloudFront distribution
Property | Type | Default | Description |
---|---|---|---|
id | string |
settings.cloudFront.id |
The CloudFront distribution id |
paths | Array<string> |
settings.cloudFront.paths |
The invalidation paths |
{
"deployment": {
"steps": {
"cloudFront.invalidate": {
"id": "OVERRIDE",
"paths": ["OVERRIDE"]
}
}
}
}
Deployment Step: s3.archive
Creates a zip archive and uploads it to an S3 bucket.
Property | Type | Default | Description |
---|---|---|---|
bucket | string |
settings.s3.bucket |
The S3 bucket name |
prefix | string |
A bucket path prefix to append to to key | |
directory | string |
The directory containing the files to upload | |
fileName | string |
The generated ZIP file name. If this is undefined , null or empty, a file name will be automatically generated based on other settings. |
|
separator | string |
_ |
File name separator |
timestamp | boolean |
false |
Append a timestamp to the file name. Defaults to and ISO string with : and . replaced with - . |
timestampFormat | string |
The date/time format string. See @evokegroup/dateformat . |
|
timestampRadix | number |
The radix to use for converting the Date into a string when a timestampFormat is not specified. |
|
guid | boolean |
false |
Appends a guid to the file name. |
ignore |
Array<string> , Array<RegExp>
|
[] |
Files to ignore when uploading |
{
"s3.archive": {
"enabled": "${S3_ARCHIVE_ENABLED}",
"bucket": "${S3_ARCHIVE}",
"directory": "static/dist",
"fileName": "archive",
"timestamp": true
}
}
Deployment Step: s3.redirectionRules
Sets the static website host redirection rules property.
Property | Type | Default | Description |
---|---|---|---|
bucket | string |
settings.s3.bucket |
The S3 bucket name |
rules |
Array<object> , string
|
An array of objects or a file containing the redirection rules. |
{
"deployment": {
"steps": {
"s3.redirectionRules": {
"bucket": "OVERRIDE",
"rules": "aws-redirection-rules.json"
}
}
}
}
Deployment Step: s3.redirects
Creates redirects in S3 by creating an empty file with the redirect specified in it's metadata.
Property | Type | Default | Description |
---|---|---|---|
bucket | string |
settings.s3.bucket |
The S3 bucket name |
redirects |
object , string
|
{} |
An object or a file containing the paths to be redirected and the redirect locations |
{
"deployment": {
"steps": {
"s3.redirects": {
"bucket": "OVERRIDE",
"redirects": "aws-redirects.jsonc"
}
}
}
}
// aws-redirects.jsonc
{
// Comments are supported in .jsonc file
"/some-page": "/somewhere-else",
"/another-page": {
"subpaths": ["index", "index.html"], // redirect /another-path/index and /another-path/index.html
"redirect": "/go-here",
"meta": {
"Cache-Control": "max-age=3600, no-transform, public"
}
}
}
Redirect Object
Property | Type | Default | Description |
---|---|---|---|
key | string |
The path to be redirected. A leading / is optional. |
|
value |
object , string
|
The path to redirect to or an object containing the redirect information. The redirect path should start with / if not redirecting to another domain. |
|
value.alts | Array<string> |
An array of alternate paths to be redirected. | |
value.exts | Array<string> |
An array of extensions to append to the path to be redirected. | |
value.subpaths | Array<string> |
An array of subpaths that should also be redirected. | |
value.redirect | string |
The redirect path. | |
value.query | object |
Query string data object | |
value.meta | object |
Override S3 metadata | |
value.redirectHeader | string |
x-amz-website-redirect-location |
The redirect header name. Override this if using the standard S3 object redirection method in not desired and the redirection will be provided by another means. |
value.track | boolean |
false |
Add tracking info |
value.trackMethod | string |
querystring |
Add tracking info via querystring or header
|
value.trackData |
object , string
|
evo_redirected=${from} |
Tracking data. string values must be in the standard query string format. Values of ${from} will be replaced with the path being redirected. Values of ${to} will be replaced with the path being redirected to. |
Basic redirect.
{
"/vanity-url": "/real-url/?utm_source=test"
}
Redirect /vanity-url
, /vanity-url.html
, and /vanity-url/index.html
.
{
"/vanity-url": {
"alts": [
"/vanity-url.html",
"/vanity-url/index.html"
],
"redirect": "/real-url/",
"query": {
"utm_source": "test"
}
}
}
Redirect /external-url
, /external-url.html
, and /external-url/index.html
and do not track.
{
"/external-url": {
"exts": [
".html"
],
"subpaths": [
"index.html"
],
"redirect": "https://www.domain.com/path?other=data",
"track": false
}
}
Set tracking for all redirects.
{
"deployment": {
"steps": {
"s3.redirects": {
"redirects": "aws-redirects.jsonc",
"track": true,
"trackData": "from=${from}"
}
}
}
}
Don't use an external file.
{
"deployment": {
"steps": {
"s3.redirects": {
"redirects": {
"/redirect-me": "/go-here/"
},
"track": true,
"trackData": {
"from": "${from}",
"to": "${to}"
}
}
}
}
}
Deployment Step: s3.removeNotDeployed
Removes any files not included in the deployment.
Property | Type | Default | Description |
---|---|---|---|
bucket | string |
settings.s3.bucket |
The S3 bucket name |
removeFiles | boolean |
true |
Remove files |
removeRedirects | boolean |
true |
Remove redirects |
removeAnyCreator | boolean |
true |
Remove a file or redirect regardless of how the file was created. To remove only files created with the library set to false
|
ignore | Array<RegExp> |
[] |
An array of regular expressions of files that should not be deleted |
{
"deployment": {
"steps": {
"s3.removeNotDeployed": {
"bucket": "OVERRIDE",
"ignore": [
"^do-not-delete.txt$"
]
}
}
}
}
Deployment Step: s3.uploadFiles
Uploads a directory to S3.
Property | Type | Default | Description |
---|---|---|---|
bucket | string |
settings.s3.bucket |
The S3 bucket name |
prefix | string |
A bucket path prefix to add to every file | |
directory | string |
null |
The directory containing the files to upload |
ignore | Array<RegExp> |
[] |
Files to ignore when uploading |
meta | object |
{} |
S3 metadata. Extends the standard configuration (services.s3.meta ) |
onlyChanged | boolean |
true |
Only upload files who's ETag is different |
{
"deployment": {
"steps": {
"s3.uploadFiles": {
"bucket": "OVERRIDE",
"directory": "static/dist",
"ignore": [
"^.*\\.htaccess$"
]
}
}
}
}
Upload to multiple buckets
{
"deployment": {
"steps": [{
"s3.uploadFiles": {
"bucket": "${S3_BUCKET_ENGLISH}",
"directory": "static/dist",
"ignore": [
"^fr\\/.*$"
]
}
}, {
"s3.uploadFiles": {
"bucket": "${S3_BUCKET_FRENCH}",
"directory": "static/dist/fr"
}
}]
}
}