​
Requirements

  1. 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).

  2. 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

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 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:

​
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.

  1. Go to the ACM console of the region
  2. Click on Request a certificate
  3. Click Next to Request a Public Certificate
  4. 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.

​
Creating and Importing Self-Signed Certificate

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.

  1. In the stack, go to Outputs and search for “cognito”
  1. Click on the Physical ID link and then on create user in the Cognito’s user pool

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

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

  1. 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.

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

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

  2. 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).

  3. 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.

  1. 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.

  2. 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

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