Getting started

To setup Bifravst on AWS, complete the following steps:

  1. Check and make sure that you have the necessary system requirements.

  2. Clone the project and install dependencies.

  3. Provide your AWS credentials.

  4. Check and verify that the deployment is planned in one of the supported regions.

  5. Install Bifravst into your AWS account.

System requirements

You need a development environment with the upcoming LTS release candidate of Node.js (current release is version 14).

If you are using Windows, use the Windows Subsystem for Linux with Ubuntu 18.04 LTS.

Note

Windows is not included in the continuous integration tests, and hence if you encounter issues, you can open an issue in the Bifravst AWS project

Clone the project and install dependencies

Clone the latest version of the Bifravst AWS project and install the dependencies using the following commands:

git clone https://github.com/bifravst/aws.git bifravst-aws
cd bifravst-aws
npm ci
npx tsc

Provide your AWS credentials

To set up Bifravst on AWS, you must first set up a new AWS account and provide the AWS credentials.

Note

It is recommended to install these resources in a blank AWS account to clearly separate them from your other projects. After you have registered your personal account, sign up for AWS Organizations and create a sub-account for Bifravst. You can have many sub-accounts, without extra costs.

To setup a new AWS account and provide credentials, complete the following steps:

  1. Navigate to your IAM console and add a new user for programmatic access.

  2. Attach the arn:aws:iam::aws:policy/AdministratorAccess policy directly.

    Note

    This action will create a user with full access rights to the account, and therefore it must only be created in an account dedicated for Bifravst.

  3. Configure the AWS CDK by referring the CDK Getting Started guide.

  4. As a recommended workflow, use a direnv plugin for your shell, which locates the environment variables in a .envrc file in the project folder and automatically exports them.

  5. Create a new .envrc file in the project folder and add the credentials that are provided to you when you create the new user.

  6. Add your preferred region and your AWS account ID (that can be found under My Account on the AWS console), to the .envrc file, as shown in the following code:

    export AWS_ACCESS_KEY_ID="<value of Access key ID>"
export AWS_SECRET_ACCESS_KEY="<value of Secret access key>"
export AWS_DEFAULT_REGION="<your preferred AWS region>"

    Note

    You must add the .envrc file to your global .gitignore file.

Supported regions

You must also confirm that you are deploying to a region that is supported.

Note

Not all AWS features are available in all AWS regions. You will see a warning if you are deploying to a region that has not been tested and the AWS CDK might fail.

Following are the supported regions:

  • us-east-1

  • us-east-2

  • us-west-1

  • us-west-2

  • eu-west-1

Install Bifravst into your AWS account

The following commands set up the necessary resources in your AWS account:

npx cdk -a 'node dist/cdk/cloudformation-sourcecode.js' deploy
npx cdk bootstrap
npx cdk deploy '*'
# This is a fix for a bug with AWS CloudFormation and HTTP APIs
# See https://github.com/bifravst/aws/issues/455
node dist/cdk/helper/addFakeRoute.js

The AWS CDK will provide a list of permission changes to your account, and you need to review them carefully whenever you make changes to the setup. However, this step is not mandatory, and you can skip it by using the following command:

npx cdk deploy '*' --require-approval never