AWS terraform
This is the documentation for how to use our terraform for AWS to set up Cobrowse Enterprise in your cloud.

Initial Setup

Make sure you have installed (on your local machine) the required tools to manage and deploy the Cobrowse infrastructure to AWS. You'll need these installed before running the setup scripts:
You'll also need an AWS account with credentials available to the setup script through the environment. This is most easily managed via the official AWS cli tools.

Installation steps

1. Database setup

The first thing you'll need is access to a MongoDB database. Cobrowse will need a connection string containing the address and authentication information for your cluster.
A MongoDB cluster is required for running Cobrowse. We do not provide this as part of the terraform environment.
You will need to create a cluster and provide the connection URL as a part of the Cobrowse configuration. You can either run your own MongoDB cluster and manage the deployment and backups yourself. Alternatively, we recommend using a hosted service such as MongoDB Atlas. They have a range of certifications required by many enterprises with compliance requirements.

2. Create an S3 bucket

Terraform will be configured to save the state of the resources it creates to an S3 bucket. This bucket must be created manually. It's access should be completely private as the terraform state may contain sensitive information.
See the AWS documentation on how to create a bucket if you are unsure about how to do this.

3. Generate the config directory

We have provided a small command line utility to help you get started. This utility will gather the required config for your deployment. Run the following command from your terminal:
1
> npx cobrowse-enterprise create aws ./example
Copied!
You can replace "./example" with the directory where you wish to save the configuration data. The directory will be created if it does not exist yet.

4. Deploy the Terraform

Once you have successfully generated a configuration directory via our command line utility you are then ready to deploy the terraform to AWS.
Navigate to the configuration directory you created and run the following commands:
1
> terraform init
Copied!
This will instruct terraform to prepare the resources it needs to deploy.
Note: During the first attempt of the following deployment an SSL certificate will be generated by Amazon Certificate Manager. During deployment you will need to head to ACM and perform the manual steps required to approve the certificate request; this is an Amazon process that requires adding a DNS record to validate domain ownership. If the deployment fails here you can safely re-run terraform apply once the certificate request has been approved. You should only need to complete this approval once for your Cobrowse domain.
Run the following command to start the deployment of resources to AWS:
1
> terraform apply
Copied!
This will list the modifications that terraform will make to your AWS account. If that looks good, type 'yes' to continue the deployment.

5. Configure your DNS provider

Once the terraform managed resources have been deployed to AWS, you should have an output similar to this:
1
Apply complete! Resources: 255 added, 0 changed, 0 destroyed.
2
3
Outputs:
4
5
dns = {
6
"api_dns_name" = "cluster-enterprise-XXXXXXXXXX.eu-west-1.elb.amazonaws.com"
7
"api_domain" = "api.example.com"
8
"api_zone_id" = "XXXXXXXXXX"
9
"frontend_dns_name" = "XXXXXXXXXX.cloudfront.net"
10
"frontend_domain" = "example.com"
11
"frontend_zone_id" = "XXXXXXXXXX"
12
}
Copied!
The last step is to configure the two required DNS records with your DNS provider (e.g. Route 53). We will not do this automatically.
Create CNAMES to direct the api_domain to the api_dns_name value shown in the output from terraform apply, and the frontend_domain to the frontend_dns_name value.

6. Check your deployment

Your deployment should now be available. Open up a web browser to your Cobrowse domain and check the deployment!

Monitoring your Deployment

Here we've listed a few useful resources created by our terraform. These can be used to check on the health of your deployment, or dig into any errors you might be experiencing:
View your cluster in ECS. There should be several services running (cobrowse-api, cobrowse-api-sockets, cobrowse-recording and cobrowse-proxy). Each should have at least one stably running task.
CloudWatch metrics for Cobrowse. Here you can see many metrics in one place, including general container metrics such as CPU and memory utilization, as well as some application metrics such as number of sessions started.
CloudWatch Logs for application level logging. Note: we recommend using a command line tool like awslogs to make viewing the aggregated log stream easier.

Managing your deployment

Next, learn about managing and upgrading your deployment.
Last modified 5mo ago