@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.

See https://docs.aws.amazon.com/AmazonS3/latest/dev/how-to-page-redirect.html#advanced-conditional-redirects

| 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"
      }
    }]
  }
}