Skip to main content

Step 3: Initialize an environment stage

ShipFast provides the ability to deploy various versions of your application, such as QA, staging, or production. You have the flexibility to determine their naming conventions and the number of environments required. The only exception is the `local` environment, which is a specialized preconfigured environment utilized for runningShipFast on local machine.

All environments can either be deployed to a single AWS account or to separate ones, depending on your cloud governance policies and preferences.

In essence, they are defined through different environmental variables. To manage these variables, the ShipFast leverages AWS Systems Manager Parameter Store and a tool called chamber. With these tools, managing environment variables is easy and secure.

caution

Before deploying the infrastructure to AWS, you must set all required environmental variables!

Install chamber CLI​

Follow the official instructions on how to install chamber.

Bootstrap CDK​

In ShipFast, AWS CDK is used to define infrastructure as a code. It also needs to create a KMS key with alias parameter_store_key that chamber is using to manage secure values.

Before you deploy anything to AWS you need to run following initialization command:

pnpm shipfast infra bootstrap

If you're deploying a second environment stage to the same AWS account as the previous one you will receive an information that bootstrap has already been run.

Set required env variables in SSM Parameter Store​

Open a shell terminal with proper AWS credentials available. If you followed a previous step you can run following command to do it:

pnpm shipfast aws set-env [STAGE_NAME]

Let's assume your stage is named qa and the project is named saas. Here's a list of all required env variables that you should set and a command that you should use to set them.

Set project name​

Each stage can have a different project name if you want but recommended approach is to use the same across all stages.

pnpm shipfast aws set-var PROJECT_NAME saas

Configure domains​

For this step you'll need the hosted zone parameters that you acquired in the previous step of this guide.

pnpm shipfast aws set-var SHIPFAST_HOSTED_ZONE_ID XYZ
pnpm shipfast aws set-var SHIPFAST_HOSTED_ZONE_NAME example.com
pnpm shipfast aws set-var SHIPFAST_DOMAIN_ADMIN_PANEL admin.qa.example.com
pnpm shipfast aws set-var SHIPFAST_DOMAIN_API api.qa.example.com
pnpm shipfast aws set-var SHIPFAST_DOMAIN_CDN cdn.qa.example.com
pnpm shipfast aws set-var SHIPFAST_DOMAIN_DOCS docs.qa.example.com
pnpm shipfast aws set-var SHIPFAST_DOMAIN_WEB_APP app.qa.example.com
info

SHIPFAST_HOSTED_ZONE_ID and SHIPFAST_HOSTED_ZONE_NAME can be skipped if you are using externally managed DNS. In that case, certificates for CloudFront distribution and Load Balancer should be already generated, and their ARNs provided in SHIPFAST_CLOUDFRONT_CERTIFICATE_ARN and SHIPFAST_LOAD_BALANCER_CERTIFICATE_ARN parameters. As the last step, CNAME DNS records pointing to CloudFront distribution and Load Balancer need to be manually added.

[Optional] Configure production domain​

ShipFast.dev creates a certificate that supports *.[ENV_STAGE].example.com domains, like app.production.example.com. You most likely don't want such domain and need straight up app.example.com for your production environment. Set a following variable to override the default behaviour:

pnpm shipfast aws set-var SHIPFAST_CERTIFICATE_DOMAIN example.com

Without setting this variable you'll encounter an error during deployment

Resource handler returned message: "Invalid request provided: AWS::CloudFront::Distribution: The certificate that is
attached to your distribution doesn't cover the alternate domain name (CNAME) that you're trying to add.

[Optional] Protect the website with basic auth​

It's a good idea to prevent unauthorized access to staging environments so we suggest to set a basic auth password if this isn't a production environment.

pnpm shipfast aws set-var SHIPFAST_BASIC_AUTH username:password

[Optional] Configure automatic deployment for selected branches​

If you want a deployment to be stared automatically when a commit is pushed to certain branch you can list them in the SHIPFAST_DEPLOY_BRANCHES variable.

pnpm shipfast aws set-var SHIPFAST_DEPLOY_BRANCHES master

[Optional] Set tools env variables​

To configure tools package env variables follow the example below.

pnpm shipfast aws set-var SHIPFAST_TOOLS_ENABLED <true/false>
pnpm shipfast aws set-var SHIPFAST_TOOLS_BASIC_AUTH username:password
pnpm shipfast aws set-var SHIPFAST_TOOLS_HOSTED_ZONE_ID XYZ
pnpm shipfast aws set-var SHIPFAST_TOOLS_HOSTED_ZONE_NAME example.com
pnpm shipfast aws set-var SHIPFAST_TOOLS_DOMAIN_VERSION_MATRIX status.example.com

Env variable validation​

You can look up the validator in packages/internal/core/stage-env-validator.js, which runs on every nx command that is executed. It will throw an error if you forget to set any required variables. Feel free to add other variables in there if you need.