> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squared.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# AWS EC2
## Deploying Multiwoven on AWS EC2 Using Docker Compose
This guide walks you through setting up Multiwoven, on an AWS EC2 instance using Docker Compose. We'll cover launching the instance, installing Docker, running Multiwoven with its dependencies, and finally, accessing the Multiwoven UI.
**Important Note:** At present, TLS is required. This means that to successfully deploy the Platform via docker-compose, you will need access to a DNS record set as well as the ability to obtain a valid TLS certificate from a Certificate Authority. You can obtain a free TLS certificates via tools like CertBot, Amazon Certificate Manager (if using an AWS Application Load Balancer to front an EC2 instance), letsencrypt-nginx-proxy-companion (if you add an nginx proxy to the docker-compose file to front the other services), etc.
**Prerequisites:**
* An active AWS account
* Basic knowledge of AWS and Docker
* A private repository access key (please contact your AIS point of contact if you have not received one)
**Notes:**
* This guide uses environment variables for sensitive information. Replace the placeholders with your own values before proceeding.
* This guide uses an Application Load Balancer (ALB) to front the EC2 instance for ease of enabling secure TLS communication with the backend using an Amazon Certificate Manager (ACM) TLS certificate. These certificates are free of charge and ACM automatically rotates them every 90 days. While the ACM certificate is free, the ALB is not. You can refer to the following document for current ALB pricing: [ALB Pricing Page](https://aws.amazon.com/elasticloadbalancing/pricing/?nc=sn\&loc=3).
**1. Obtain TLS Certificate (Requires access to DNS Record Set)**
**1.1** In the AWS Management Console, navigate to Amazon Certificate Manager and request a new certificate.
1.2 Unless your organization has created a Private CA (Certificate Authority), we recommend requesting a public certificate.
1.3 Request a single ACM certificate that can verify all three of your chosen subdomains for this deployment. DNS validation is recommended for automatic rotation of your certificate but this method requires access to your domain's DNS record set.
1.4 Once you have added your selected sub-domains, scroll down and click **Request**.
5. Once your request has been made, you will be taken to a page that will describe your certificate request and its current status. Scroll down a bit and you will see a section labeled **Domains** with 3 subdomains and 1 CNAME validation record for each. These records need to be added to your DNS record set. Please refer to your organization's internal documentation or the documentation of your DNS service for further instruction on how to add DNS records to your domain's record set.
**Note:** For automatic certificate rotation, you need to leave these records
in your record set. If they are removed, automatic rotation will fail.
6. Once your ACM certificate has been issued, note the ARN of your certificate and proceed.
**2. Create and Configure Application Load Balancer and Target Groups**
1. In the AWS Management Console, navigate to the EC2 Dashboard and select **Load Balancers**.
{" "}
2. On the next screen select **Create** under **Application Load Balancer**.
{" "}
3. Under **Basic configuration** name your load balancer. If you are deploying this application within a private network, select **Internal**. Otherwise, select **Internet-facing**. Consult with your internal Networking team if you are unsure as this setting can not be changed post-deployment and you will need to create an entirely new load balancer to correct this.
{" "}
4. Under **Network mapping**, select a VPC and write it down somewhere for later use. Also, select 2 subnets (2 are **required** for an Application Load Balancer) and write them down too for later use.
**Note:** If you are using the **internal** configuration, select only **private** subnets. If you are using the **internet-facing** configuration, you must select **public** subnets and they must have routes to an **Internet Gateway**.
5. Under **Security groups**, select the link to **create a new security group** and a new tab will open.
6. Under **Basic details**, name your security group and provide a description. Be sure to pick the same VPC that you selected for your load balancer configuration.
7. Under **Inbound rules**, create rules for HTTP and HTTPS and set the source for both rules to **Anywhere**. This will expose inbound ports 80 and 443 on the load balancer. Leave the default **Outbound rules** allowing for all outbound traffic for simplicity. Scroll down and select **Create security group**.
8. Once the security group has been created, close the security group tab and return to the load balancer tab. On the load balancer tab, in the **Security groups** section, hit the refresh icon and select your newly created security group. If the VPC's **default security group** gets appended automatically, be sure to remove it before proceeding.
9. Under **Listeners and routing** in the card for **Listener HTTP:80**, select **Create target group**. A new tab will open.
10. Under **Basic configuration**, select **Instances**.
11. Scroll down and name your target group. This first one will be for the Platform's web app so you should name it accordingly. Leave the protocol set to HTTP **but** change the port value to 8000. Also, make sure that the pre-selected VPC matches the VPC that you selected for the load balancer. Scroll down and click **Next**.
12. Leave all defaults on the next screen, scroll down and select **Create target group**. Repeat this process 2 more times, once for the **Platform API** on **port 3000** and again for **Temporal UI** on **port 8080**. You should now have 3 target groups.
13. Navigate back to the load balancer configuration screen and hit the refresh button in the card for **Listener HTTP:80**. Now, in the target group dropdown, you should see your 3 new target groups. For now, select any one of them. There will be some further configuration needed after the creation of the load balancer.
14. Now, click **Add listener**.
15. Change the protocol to HTTPS and in the target group dropdown, again, select any one of the target groups that you previously created.
16. Scroll down to the **Secure listener settings**. Under **Default SSL/TLS server certificate**, select **From ACM** and in the **Select a certificate** dropdown, select the certificate that you created in Step 1. In the dropdown, your certificate will only show the first subdomain that you listed when you created the certificate request. This is expected behavior.
**Note:** If you do not see your certificate in the dropdown list, the most likely issues are:
(1) your certificate has not yet been successfully issued. Navigate back to ACM and verify that your certificate has a status of **Issued**.
(2) you created your certificate in a different region and will need to either recreate your load balancer in the same region as your certificate OR recreate your certificate in the region in which you are creating your load balancer.
17. Scroll down to the bottom of the page and click **Create load balancer**. Load balancers take a while to create, approximately 10 minutes or more. However, while the load balancer is creating, copy the DNS name of the load balancer and create CNAME records in your DNS record set, pointing all 3 of your chosen subdomains to the DNS name of the load balancer. Until you complete this step, the deployment will not work as expected. You can proceed with the final steps of the deployment but you need to create those CNAME records.
18. At the bottom of the details page for your load balancer, you will see the section **Listeners and rules**. Click on the listener labeled **HTTP:80**.
19. Check the box next to the **Default** rule and click the **Actions** dropdown.
20. Scroll down to **Routing actions** and select **Redirect to URL**. Leave **URI parts** selected. In the **Protocol** dropdown, select **HTTPS** and set the port value to **443**. This configuration step will automatically redirect all insecure requests to the load balancer on port 80 (HTTP) to port 443 (HTTPS). Scroll to the bottom and click **Save**.
21. Return to the load balancer's configuration page (screenshot in step 18) and scroll back down to the *Listeners and rules* section. This time, click the listener labled **HTTPS:443**.
22. Click **Add rule**.
23. On the next page, you can optionally add a name to this new rule. Click **Next**.
24. On the next page, click **Add condition**. In the **Add condition** pop-up, select **Host header** from the dropdown. For the host header, put the subdomain that you selected for the Platform web app and click **Confirm** and then click **Next**.
25. One the next page, under **Actions**. Leave the **Routing actions** set to **Forward to target groups**. From the **Target group** dropdown, select the target group that you created for the web app. Click **Next**.
26. On the next page, you can set the **Priority** to 1 and click **Next**.
27. On the next page, click **Create**.
28. Repeat steps 24 - 27 for the **api** (priority 2) and **temporal ui** (priority 3).
29. Optionally, you can also edit the default rule so that it **Returns a fixed response**. The default **Response code** of 503 is fine.
**3. Launch EC2 Instance**
1. Navigate to the EC2 Dashboard and click **Launch Instance**.
2. Name your instance and select **Ubuntu 22.04 or later** with **64-bit** architecture.
3. For instance type, we recommend **t3.large**. You can find EC2 on-demand pricing here: [EC2 Instance On-Demand Pricing](https://aws.amazon.com/ec2/pricing/on-demand). Also, create a **key pair** or select a pre-existing one as you will need it to SSH into the instance later.
4. Under **Network settings**, click **Edit**.
5. First, verify that the listed **VPC** is the same one that you selected for the load balancer. Also, verify that the pre-selected subnet is one of the two that you selected earlier for the load balancer as well. If either is incorrect, make the necessary changes. If you are using **private subnets** because your load balancer is **internal**, you do not need to auto-assign a public IP. However, if you chose **internet-facing**, you may need to associate a public IP address with your instance so you can SSH into it from your local machine.
6. Under **Firewall (security groups)**, we recommend that you name the security group but this is optional. After naming the security security group, click the button \*Add security group rule\*\* 3 times to create 3 additional rules.
7. In the first new rule (rule 2), set the port to **3000**. Click the **Source** input box and scroll down until you see the security group that you previously created for the load balancer. Doing this will firewall inbound traffic to port 3000 on the EC2 instance, only allowing inbound traffic from the load balancer that you created earlier. Do the same for rules 3 and 4, using ports 8000 and 8080 respectively.
8. Scroll to the bottom of the screen and click on **Advanced Details**.
9. In the **User data** box, paste the following to automate the installation of **Docker** and **docker-compose**.
```
Content-Type: multipart/mixed; boundary="//"
MIME-Version: 1.0
--//
Content-Type: text/cloud-config; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="cloud-config.txt"
#cloud-config
cloud_final_modules:
- [scripts-user, always]
--//
Content-Type: text/x-shellscript; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="userdata.txt"
#!/bin/bash
sudo mkdir ais
cd ais
# install docker
sudo apt-get update
yes Y | sudo apt-get install apt-transport-https ca-certificates curl software-properties-common
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
echo | sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
yes Y | sudo apt-get install docker-ce
sudo systemctl status docker --no-pager && echo "Docker status checked"
# install docker-compose
sudo apt-get install -y jq
VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r .tag_name)
sudo curl -L "https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version
sudo systemctl enable docker
```
10. In the right-hand panel, click **Launch instance**.
**4. Register EC2 Instance in Target Groups**
1. Navigate back to the EC2 Dashboard and in the left panel, scroll down to **Target groups**.
2. Click on the name of the first listed target group.
3. Under **Registered targets**, click **Register targets**.
4. Under **Available instances**, you should see the instance that you just created. Check the tick-box next to the instance and click **Include as pending below**. Once the instance shows in **Review targets**, click **Register pending targets**.
5. **Repeat steps 2 - 4 for the remaining 2 target groups.**
**5. Deploy AIS Platform**
1. SSH into the EC2 instance that you created earlier. For assistance, you can navigate to your EC2 instance in the EC2 dashboard and click the **Connect** button. In the **Connect to instance** screen, click on **SSH client** and follow the instructions on the screen.
2. Verify that **Docker** and **docker-compose** were successfully installed by running the following commands
```
sudo docker --version
sudo docker-compose --version
```
You should see something similar to
3. Change directory to the **ais** directory and download the AIS Platform docker-compose file and the corresponding .env file.
```
cd \ais
sudo curl -LO https://multiwoven-deployments.s3.amazonaws.com/docker/docker-compose/docker-compose.yaml
sudo curl -LO https://multiwoven-deployments.s3.amazonaws.com/docker/docker-compose/.env.production && sudo mv /ais/.env.production /ais/.env
```
Verify the downloads
```
ls -a
```
You should see the following
4. You will need to edit both files a little before deploying. First open the .env file.
```
sudo nano .env
```
**There are 3 required changes.**
**(1)** Set the variable **VITE\_API\_HOST** so the UI knows to send requests to your **API subdomain**.
**(2)** If not present already, add a variable **Track** and set its value to **no**.
**(3)** If not present already, add a variable **ALLOWED\_HOST**. The value for this is dependent on how you selected your subdomains earlier. This variable only allows for a single step down in subdomain so if, for instance, you selected ***app.mydomain.com***, ***api.mydomain.com*** and ***temporal.mydomain.com*** you would set the value to **.mydomain.com**.
If you selected ***app.c1.mydomain.com***, ***api.c1.mydomain.com*** and ***temporal.c1.mydomain.com*** you would set the value to **.c1.mydomain.com**.
For simplicity, the remaining defaults are fine.
Commands to save and exit **nano**.
**Mac users:**
```
- to save your changes: Control + S
- to exit: Control + X
```
**Windows users:**
```
- to save your changes: Ctrl + O
- to exit: Ctrl + X
```
5. Next, open the **docker-compose** file.
```
sudo nano docker-compose.yaml
```
The only changes that you should make here are to the AIS Platform image repositories. After opening the docker-compose file, scroll down to the Multiwoven Services and append **-ee** to the end of each repostiory and change the tag for each to **edge**.
Before changes
After changes
6. Deploy the AIS Platform. This step requires a private repository access key that you should have received from your AIS point of contact. If you do not have one, please reach out to AIS.
```
DOCKERHUB_USERNAME="multiwoven"
DOCKERHUB_PASSWORD="YOUR_PRIVATE_ACCESS_TOKEN"
sudo docker login --username $DOCKERHUB_USERNAME --password $DOCKERHUB_PASSWORD
sudo docker-compose up -d
```
You can use the following command to ensure that none of the containers have exited
```
sudo docker ps -a
```
7. Return to your browser and navigate back to the EC2 dashboard. In the left panel, scroll back down to **Target groups**. Click through each target group and verify that each has the registered instance showing as **healthy**. This may take a minute or two after starting the containers.
8. Once all target groups are showing your instance as healthy, you can navigate to your browser and enter the subdomain that you selected for the AIS Platform web app to get started!