Skip to main content
A CloudFormation stack that provisions the network, the database and the service in one go.

​
Requirements

1

Admin permissions

Deploying the stack creates resources across several services, so the deploying user needs Admin permissions. The exact resource set changes between releases, which is why we do not publish a narrower policy.
2

A dedicated AWS account

We recommend an isolated account. It keeps service quota collisions out of the picture and makes the install easier to reason about.

​
Deploy the stack

Pick your region and click through the CloudFormation console:

us-east-1

N. Virginia

us-east-2

Ohio

us-west-1

N. California

us-west-2

Oregon

eu-west-1

Ireland

eu-west-2

London

eu-central-1

Frankfurt

ap-southeast-2

Sydney
The default parameters suit most organizations. The one thing you have to supply is an ACM certificate matching a public DNS record.

​
Issue the certificate

  1. Open the ACM console in your region.
  2. Click Request a certificate.
  3. Click Next to request a public certificate.
  4. Choose your domain and a validation method, then click Request.
The certificate stays pending until you validate it, and how you validate depends on the method you picked.
Requesting a certificate in ACM
Open the certificate entry, follow the validation instructions, and copy its ARN. The status turns green once validation completes.
A validated ACM certificate
Pass that ARN as the AwsCertificateArn parameter when you deploy.

​
Point DNS at it

  1. Wait for every item under Stacks to read CREATE_COMPLETE, then click the stack.
A completed CloudFormation stack
  1. Open the Outputs tab and copy the load balancer address. Create a CNAME record pointing the domain on your certificate at that address.
The stack outputs tab
To test before publishing anything to DNS, resolve the load balancer’s public IP and add it to your hosts file:

​
Sign in

Visit the public DNS you set in the AppPublicDNS parameter — https://yourdomain.tld. Click Create one to create the first user. Authentication is local by default: the Control Plane manages users and passwords itself, so there is nothing to configure before you can log in.
The sign-up page

​
What the stack creates

  • A Virtual Private Cloud (VPC)
  • Two public subnets
  • Two private subnets, with NAT gateways
  • Two isolated subnets
  • An RDS Postgres database
  • An Auto Scaling group with EC2 instances
  • Secrets Manager secrets for the Postgres password and access credentials
  • An Application Load Balancer
  • Security groups restricting access to the infrastructure — only 443 and 8443 reach the load balancer, and nothing reaches RDS directly

​
Updating

Keep the installation in sync with the releases you want. Read the release notes first so you know what is changing.
1

Start the update

CloudFormation → select the installed stack → Update.
Updating the stack
2

Replace the template

Choose Replace Existing Template and enter the URL for your region:Check that the region in the URL matches the region in the console’s top-right selector. If the console says “Virginia” and the dropdown highlights us-east-1, then us-east-1 should appear in the URL — three times.
3

Set failure handling

Set Stack failure options to Roll back all stack resources, then click Next. With it set to preserve, CloudFormation refuses to deploy certain kinds of change.
Stack failure options
4

Apply it

Check both permission boxes at the bottom and click Update Stack. You do not need to wait for the change set to load.Some updates finish in minutes and some take hours. If the update fails, screenshot the failure under Events in the stack — and if a nested stack is what failed, screenshot the Events of that nested stack too.

​
Uninstalling

CloudFormation → select the installed stack → Delete.

​
Next

Connect a Sidecar

Issue a token, point a Sidecar at the server host, and confirm it picked up its configuration.