Provisioning a brand new Dev Environment - alphagov/notifications-manuals GitHub Wiki

The high level steps to create a new developer environment:

Requesting a new AWS account

To vend a new AWS account go to the Engineering Excellence hub and follow the current guidance, contact the slack channel gds-engineering-enablement slack channel for queries.

When following the instructions on filling out the new AWS account template remember to include yourself as a bootstrap-admin when raising a PR for the account addition (once the account has been vended, admins will be emailed instructions on how to login and set up the account).

Ask for review from the EE team on the slack channel #gds-engineering-enablement.

Upon completion of the vending process you need to purchase a domain for the new dev account complete the steps outlined in the README.

Add configuration to account-wide-terraform

Complete the following in the account-wide-terraform repo:

  • If a .terraform folders exists in your local directory below then delete it:

    /path/to/notifications-aws-account-wide-terraform/terraform/deployments/notify-env

  • In the same directory you must define the tfvar file at ./tfvars and backend file at ./backends for the new environment using an existing one as a template and replacing all instances of the dev environment name (e.g. in the case of defining a new dev environment dev-e: dev-a.tfvars becomes dev-e.tfvars, dev-a.backend becomes dev-e.backend, env = dev-a becomes env = dev-e etc.).

  • Use this PR as a mirror for any other changes, and commit them to a PR.

Add configuration to notifications-aws

Use this PR as a mirror to make additions required for your new dev environment.

Bootstrapping the AWS account:

You must go through the bootstrap process so that the new AWS account has the IAM roles and capabilities needed to run Notify.

Run the make bootstrap target below replacing dev-e with the name of your new dev environment:

cd /path/to/notifications-aws-account-wide-terraform/
make bootstrap dev-e

This step will create the IAM roles, a state file S3 bucket, and state locking dynamoDB table called notifications-aws-account-wide-terraform in the new dev environment's AWS account

Adding the environment specific credentials:

Checkout the latest copy of notifications-credentials locally and copy the entries from one of the other dev environments e.g. dev-a:

/path/to/notifications-credentials/credentials/dev-a

You will need to go through an edit parameters to be specific to your new dev environment. Specifically use the commands:

pass edit credentials/dev-name/concourse-ssm/dns_name
pass edit credentials/dev-name/sqlalchemy_database_uri

These will open a vim editor which you can use to amend the credentials to reflect the name of your new dev environment.

Adding Identities to the SES sandbox (region eu-west-1 Ireland):

The functional tests will not pass until a specific google user has been added to the SES sandbox as a trusted identity.

You must add the email address below to the SES sandbox trusted identities list for the new AWS account. Without this step the functional tests will fail:

[email protected]

You must verify the addition by clicking on the verification link in the email. NB this user was a google user rather than a google group, meaning that the account had to be recovered in the last attempt to add a new dev environment (Sept 2025). A ticket has been raised to convert this email address into a google group but if this has not been done you will need to use a recovery code to recover the account. Be aware that several codes have already been used so either the work to convert to a group should be done, or more thought put into ongoing use of this account:

You can access the recovery codes using:

pass credentials/functional-tests/notify-tests-preview-email-2fa-backup-codes

Initialising the pipeline

After successfully bootstrapping the AWS account, you should create the entries in notifications-concourse-deployment mirroring this PR.

Now upload the environment specific credentials using the upload-credentials.sh script, and set the pipeline variables using the set-pipeline-vars make target.

The new teams will now appear in concourse after running the "deploy" pipeline (this is not the main pipeline, this is the concourse deployment pipeline).

Once this is done you will find a pipeline called "info" in the new team for your dev environment. Run this pipeline to initialise the deploy-notify pipeline. After running this you will see that the pipeline exists, but the jobs are grey (they only turn green after first run).