Skip to main content

Initial setup


  • AWS account with admin role
  • A domain

AWS vault profile

Create profiles

This profile will be used by Make when running any commands that communicate with AWS platform.

aws-vault add <your-personal-user-name>

You should find your Enter Access Key Id and Enter Secret Key in
the My security credentials section of your AWS web panel.

Next you should create a profile for the project admin (connect your account with the admin role). For that purpose you need to manually edit aws config file. As this profile name will be vastly used we recommend to keep it very short (max 4 chars, e.g "saas").

open ~/.aws/config

add new section (example below) and save the file

[profile saas]
source_profile = your-personal-user-name
role_arn = arn:aws:iam::123456789:role/SaaSBoilerplateAdminRole

Values to save:

  • name of the second aws-vault profile (saas from the example above). This is the AWS Profile name which you specify when using the script.

Multi-factor authentication

It may be also required to configure MFA for your AWS user and AWS Vault profile.

If during the deployment you encounter similar error:

infra/cdk$ npm run cdk deploy *CiStack

3:25:45 PM | UPDATE_FAILED | AWS::CodeBuild::Project | PipelineConfigWebA...ildProject04B4719B
AccessDenied. User doesn't have permission to call iam:GetRole

consider configuring MFA, as documented in the official docs.

Copy the serial MFA device serial number

MFA serial number

And paste it into the ~/.aws/config as mfa_serial property (example below) and save the file.

[profile saas]
source_profile = your-personal-user-name
role_arn = arn:aws:iam::123456789:role/SaaSBoilerplateAdminRole

Unfortunately, from now on, you will have to enter MFA every time you log into the AWS console or run aws-vault

Main config file

Now you can use that profile name in .awsboilerplate.json file

"projectName": "saas",
"defaultEnv": "qa",
"aws": {
"profile": "saas",
"region": "eu-west-1"

AWS vault usage

From now on you can use aws-vault for secure connection with AWS platform. Always make sure you are in a proper aws-vault context when you run commands that use AWS CLI. We created a make rule that simplifies this process:

make aws-vault

This command will use default environment (more about them in next section), which is being set as defaultEnv in .awsboilerplate.json.

You can also manually select environment context by passing it directly:

make aws-vault ENV_STAGE=qa

Check out the usage docs for more info about how you can utilize aws-vault.

Create a hosted zone

In order to access any environment you need to have a public Hosted Zone in AWS Route53. AWS boilerplate will use this hosted zone's domain to route traffic to your app.

A hosted zone is a container for records, and records contain information about how you want to route traffic for a specific domain, such as, and its subdomains (, A hosted zone and the corresponding domain have the same name.

Source: AWS docs

Depending on your use case there are multiple approaches to creating a hosted zone:

  1. You don't have a domain yet.

  2. You have a domain registered in external DNR (e.g. GoDaddy).

  3. You have a domain in Route53 already and want to create a subdomain for the env.

  4. You have a domain in Route53 already.

    • You most likely already have a hosted zone! You're good to go.

Values to save:

  • id of the hosted zone
  • name of the hosted zone

Bootstrap CDK

Switch to AWS context using aws-vault to get access to role with admin rights

make aws-vault ENV_STAGE=qa
Config issue

Despite the fact that in this case we don't need any environment context (only admin role), currently there is configuration issue that will use env context any way, so please DONT use local env in this case.

Run CDK bootstrap

make bootstrap-infra

Deploy Global Infrastructure to AWS

Next up is the global infrastructure CDK stack to create the foundations of your system. Resources created in this step will be used by all environments that you'll create in the future.

make deploy-global-infra

In case of deployment failure related to certificate issues. You might simply try to make the deploy again.

Another part of the global infrastructure are the base images for all services. To create them, run the CodeBuild project <project name>-base-images.

Setup Docker Hub account

We need to setup dockerhub credentials in order receive access to their images base. You can create new dockerhub account (there is a free tier) or get access to a existing one from the client. Third option is to use guest account (empty credentials) but in that case there is a very limited number daily downloads which is shared with other AWS users which will cause builds to fail randomly (quite often).

To setup dockerhub credentials go to AWS web panel, access Secrets manager and select GlobalBuildSecrets, now find Secret value section and click Retrieve secret value and then edit. This secret may initially be set to a placeholder value, which you can delete.

Secret's value have to be an object:

"DOCKER_PASSWORD": "password123"
Dev Tools

This is also a good time to deploy our helper tools. More info can be found here