AWS

This deployment leverages AWS CloudFormation to automatically create resources and set up the Hoop in your own AWS account.

Requirements

Admin permissions

A user with Admin permissions is required in order to deploy the stack and create the resources described below. Resources used are subject to change in the future, which is why we currently recommend Admin permissions (and an isolated AWS account, mentioned below).

Dedicated AWS account

We recommend deploying the Platform in an isolated AWS account. This reduces the risk of errors, such as hitting AWS service resource limits, and overall makes things simpler to manage.

Setup

To deploy the Stack, press one of the following region-specific deploy buttons, and click through the AWS web GUI console.

us-east-1 (N. Virginia) deployment

us-east-2 (Ohio) deployment

us-west-1 (N. California) deployment

us-west-2 (Oregon) deployment

eu-west-1 (Ireland) deployment

eu-west-2 (London) deployment

eu-central-1 (Frankfurt) deployment

ap-southeast-2 (Sydney) deployment

The default parameters are appropriate for many organizations. The installation requires providing an ACM certificate matching a valid public DNS record. There are two options to proceed with this step that are described below:

a) Creating a Valid Certificate

This is the recommended approach. It will require validating a domain of your setup to emit a valid certificate that could be used in this setup.

Go to the ACM console of the region

Click on Request a certificate

Click Next to Request a Public Certificate

Choose your domain and validation Method and click on Request

The certificate will remain pending until you validate, depending on the chosen method.

Access the certificate ID entry and follow the instructions to validate the certificate. Copy its ARN. Once you finish validating it, the status will change to green.

b) Creating and Importing Self Signed Certificate

In case you want to use a self signed certificate and import into AWS, the script bellow will generate all required certificates to import in AWS ACM.

shell
#!/bin/bash -e

DOMAIN=$1

openssl genrsa -out rootCA.key 4096
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt \
    -subj "/C=US/ST=CA/O=FakeOrg, Inc./CN=fakeorg"

openssl genrsa -out $DOMAIN.key 2048
openssl req -new -sha256 -key $DOMAIN.key \
    -subj "/C=US/ST=CA/O=FakeOrg, Inc./CN=$DOMAIN" -out $DOMAIN.csr
openssl x509 -req -in $DOMAIN.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial \
    -out $DOMAIN.crt -days 500 -sha256

generate-self-signed-certs.sh

💡

Make sure to run these commands in a operating systems that contain the openssl command line utility.

Running this script will generate the follow files:

shell
./generate-self-signed-certs.sh mydomain.com

rootCA.crt The Certificate Authority certificate (Certificate Chain)

mydomain.com.crt The certificate of the server (Certificate body)

mydomain.com.key The certificate private key of the server (Certificate private key)

With this information in hand, import these files to ACM

Access the certificate ID and copy the ARN.

Now, copy the ARN in the AwsCertificateArn parameter and add the domain of the certificate in the parameter AppPublicDNS .

1. Once the deployment has completed (you should see "CREATE_COMPLETE" on all items under "Stacks"), click in the stack and then in the tab Outputs.

Copy the load balancer address and create a CNAME record in your DNS management service pointing to the domain specified in your certificate.

💡

If you want to test it without publishing it in your DNS system, obtain the load balancer's public IP and add it to your Hosts file. This will allow you to visit the app address using the DNS configured in the certificate.

View Dashboard

The setup uses AWS Cognito by default, you’ll need to add the first user and then to login.

In the stack, go to Outputs and search for “cognito”

Click on the Physical ID link and then on create user in the Cognito's user pool

Now, visit the public DNS link provided in the parameter AppPublicDNS: https://yourdomain.tld

Now, fill out the form with your Email and Password and Sign In

You’ll be redirected to the main screen, where you can choose which service to connect

💡

If you choose to import a self-signed certificate, make sure to import the rootCA.crt in your system properly to bypass the self-signed warning.

Resources deployed

Virtual Private Cloud (VPC)

Two Public Subnets

Two Private Subnets (with NAT Gateways)

Two Isolated Subnets

AWS Cognito (Optional)

RDS Postgres Database

Auto Scaling Group with EC2 Instances

EBS Volume used by EC2 Instances

Secrets Manager secrets for Postgres Password and access credentials

Application Load Balancer

Security Groups to restrict access to the infrastructure (only port 443 and 8443 to the Load Balancer, no access to the RDS databases, etc.)

Custom Identity Provider

It's possible to bring your own identity provider to authenticate your users with Hoop. By default it creates Cognito if the parameter AppIDPURI is left empty. To specify a custom one, visit our SSO documentation.

⚠️

Providing a custom IDP will remove the provisioned Cognito resources.

How to Update

You’ll need to update if you want to keep your installation in sync with the latest releases. Make sure to see exactly the changes on our release page to plan the updates carefully.

Go to CloudFormation > Select the installed stack > Click on Update

Choose Replace Existing Template and enter the URL below, which corresponds to your deployment region:

us-east-1 https://hoopdev-platform-cf-us-east-1.s3.us-east-1.amazonaws.com/latest/hoopdev-platform.template.yaml

us-east-2 https://hoopdev-platform-cf-us-east-2.s3.us-east-2.amazonaws.com/latest/hoopdev-platform.template.yaml

us-west-1 https://hoopdev-platform-cf-us-west-1.s3.us-west-1.amazonaws.com/latest/hoopdev-platform.template.yaml

us-west-2 https://hoopdev-platform-cf-us-west-2.s3.us-west-2.amazonaws.com/latest/hoopdev-platform.template.yaml

eu-west-1 https://hoopdev-platform-cf-eu-west-1.s3.eu-west-1.amazonaws.com/latest/hoopdev-platform.template.yaml

eu-west-2 https://hoopdev-platform-cf-eu-west-2.s3.eu-west-2.amazonaws.com/latest/hoopdev-platform.template.yaml

eu-central-1 https://hoopdev-platform-cf-eu-central-1.s3.eu-central-1.amazonaws.com/latest/hoopdev-platform.template.yaml

ap-southeast-2 https://hoopdev-platform-cf-ap-southeast-2.s3.ap-southeast-2.amazonaws.com/latest/hoopdev-platform.template.yaml

Double-check that the URL pasted into shows the same region as the AWS console highlights when you click on the region in the upper right. E.g., if "Virginia" is shown and the drop-down highlights us-east-1, then us-east-1 should appear as the URL (three times).

Select Next, leave all parameters as is unless asked to do otherwise, and then Next again.

If a parameter is blank or you're unsure, please reach out!

Ensure that "Stack failure options" is set to "Roll back all stack resources" and select Next.

If deployment issues arise, we may ask you to change this, but if set to preserve, CF will refuse to deploy certain types of changes.

Check both of the boxes around permissions at the bottom and select Update Stack.

You don't need to wait for the change set to load.

Occasionally monitor the status of the deployment -- some updates can take hours, others just minutes.

If the stack update does fail please take a screenshot of the failure under "Events" in the stack. If it says that a nested stack failed to deploy, include a screenshot of the "Events" in the failed nested stack. We apologize for the issue! CloudFormation is a very sensitive and particular system, as well as being subject to transient issues from an array of AWS services!

Uninstallation

Visit AWS CloudFormation in the region where you are deployed.

Select the Hoop Stack and then click on Delete.