/ember-cli-deploy-fastboot-app-server-aws

Primary LanguageJavaScriptMIT LicenseMIT

ember-cli-deploy-fastboot-app-server-aws CircleCI

An ember-cli-deploy plugin to deploy Ember FastBoot apps that are deployed via fastboot-app-server to AWS (S3)

This plugin is not a standalone plugin. You will need to have a zipped fastboot-build available on the deployment context. This plugin works best in combination with ember-cli-deploy-fastboot-app-server.

What is an ember-cli-deploy plugin?

A plugin is an addon that can be executed as a part of the ember-cli-deploy pipeline. A plugin will implement one or more of the ember-cli-deploy's pipeline hooks.

For more information on what plugins are and how they work, please refer to the Plugin Documentation.

Quick Start

To get up and running quickly, do the following:

$ ember install ember-cli-deploy-fastboot-app-server-aws
  • Run the pipeline
$ ember deploy production

ember-cli-deploy Hooks Implemented

For detailed information on what plugin hooks are and how they work, please refer to the Plugin Documentation.

  • configure
  • upload
  • fetchInitialRevisions
  • fetchRevisions
  • activate

Configuration Options

For detailed information on how configuration of plugins works, please refer to the Plugin Documentation.

accessKeyId

The AWS access key for the user that has the ability to upload to the bucket. If this is left undefined, the normal AWS SDK credential resolution will take place.

Default: undefined

secretAccessKey

The AWS secret for the user that has the ability to upload to the bucket. This must be defined when accessKeyId is defined.

Default: undefined

bucket (required)

The AWS bucket that the files will be uploaded to.

Default: undefined

region (required)

The region your bucket is located in. (e.g. set this to eu-west-1 if your bucket is located in the 'Ireland' region)

Default: undefined

revisionKey

The unique revision number for the version of the app. By default this option will use either the revision passed in from the command line or the revisionData.revisionKey property from the deployment context.

Default: context.commandOptions.revision || context.revisionData.revisionKey

archivePrefix

The prefix that will be used in combination with a revisionKey to build up the identifier for the revision you are deploying. In the default case this gets added to the deploy context via ember-cli-deploy-fastboot-app-server.

Default: context.fastbootArchivePrefix (added by ember-cli-deploy-fastboot-app-server)

downloaderManifestContent

A function that gets added to the deploy context so that other plugins can update an app-manifest file that is used by fastboot-app-server notifiers and -downloaders to update the FastBoot-app served via fastboot-app-server.

Default: context.fastbootDownloaderManifestContent (added by ember-cli-deploy-fastboot-app-server)

TL;DR

What does this plugin do exactly?

This plugin is meant to be used in combination with ember-cli-deploy-fastboot-app-server. This plugin will upload the zipped fastboot-build to S3 and can be used to implement the lightning-strategy that you are used to with ember-cli-deploy with FastBoot-applications.

This means you can list available revisions via ember deploy:list and switch around the revisions that are served to you users via the ember deploy:activate-command.

How do I activate a revision?

A user can activate a revision by either:

  • Passing a command line argument to the deploy command:
$ ember deploy --activate=true
  • Running the deploy:activate command:
$ ember deploy:activate --revision <revision-key>
  • Setting the activateOnDeploy flag in deploy.js
ENV.pipeline = {
  activateOnDeploy: true
}

What does activation do?

When ember-cli-deploy-fastboot-app-server uploads a zipped FastBoot-build-file to S3, it uploads it under the key defined by a combination of the two config properties archivePrefix and revisionKey.

So, if the archivePrefix was configured to be dist- and there had been a few revisons deployed, then your bucket might look something like this:

$ aws s3 ls s3://<bucket>/
                           PRE assets/
2017-07-15 07:47:42       1207 fastboot-deploy-info.json
2017-07-15 07:25:51       1207 dist-a644ba43cdb987288d646c5a97b1c8a9.zip
2017-07-15 07:20:27       1207 dist-61cfff627b79058277e604686197bbbd.zip
2017-07-15 07:19:11       1207 dist-9dd26dbc8f3f9a8a342d067335315a63.zip

To activate a revision the plugin will update the contents of fastboot-deploy-info.json to point to the passed revision as the active revision. As soon as manifest-file has been updated an fastboot-app-server-notifier will notice the update and trigger an fastboot-app-server-downloader to update the version of your application served via a fastboot-app-server.

$ ember deploy:activate --revision a644ba43cdb987288d646c5a97b1c8a9

When does activation occur?

Activation occurs during the activate hook of the pipeline. By default, activation is turned off and must be explicitly enabled by one of the 3 methods above.

Prerequisites

The following properties are expected to be present on the deployment context object:

Running Tests

You need to have a bucket on S3 setup for the test to complete. Tests expect specific environment variables to be set so that tests are able to upload to s3 automatically:

  • AWS_ACCESS_KEY_ID - to authenticate with AWS
  • AWS_SECRET_ACCESS_KEY - to authenticate with AWS
  • TEST_BUCKET - the name of the test bucket
  • TEST_REGION - the region the test bucket is located in

To run tests:

  • yarn test