Configuring TLS with the OpenOps script (DOC-90) (#133)

Author: gorohoroh

getting-started/deployment/aws-ec2.mdx

@@ -6,6 +6,7 @@ icon: 'aws'
 
 import AutoInstall from '/snippets/auto-install.mdx'
 import Disclaimer from '/snippets/non-production-disclaimer.mdx';
+import TLS from '/snippets/tls.mdx';
 import UpdateCredentials from '/snippets/env-update-credentials.mdx';
 import UpdateLink from '/snippets/update-link.mdx';
 
@@ -96,72 +97,7 @@ After making changes, restart the Docker Compose containers:
 sudo docker compose down && sudo docker compose up -d
 ```
 
-## Configuring TLS (HTTPS) and a custom domain
-
-For production usage, it’s recommended to enable TLS (HTTPS). In addition to the security aspect, this also ensures that [workflow templates](/workflow-management/workflow-templates/) load properly in all browsers.
-
-TLS requires configuring a custom domain (e.g., `https://openops.your-company.com`) to serve your OpenOps installation instead of its public IP address.
-
-To get a custom domain with TLS up and running, you need to set up an AWS Application Load Balancer (ALB) with a valid TLS certificate from AWS Certificate Manager (ACM), then create a new DNS record and update your OpenOps configuration.
-
-### Request an ACM certificate
-
-1. Open the [ACM console](https://console.aws.amazon.com/acm/home).
-2. Request a public certificate for your domain (e.g., `openops.your-company.com`).
-3. Validate the domain using DNS. If you're using Route 53, ACM can create the necessary records automatically.
-4. Wait until the certificate status changes to **Issued**.
-
-### Create an Application Load Balancer
-
-<Warning>Once the ALB is in place, all access should go through it — you can no longer use the EC2 public IP directly.</Warning>
-
-1. In the **EC2 > Load Balancers** section, click **Create Load Balancer**.
-2. Choose **Application Load Balancer**, and configure the following:
-    * **Scheme**: Internet-facing
-    * **Listeners**:
-        * Add a listener for **HTTPS (443)** using the ACM certificate.
-        * Optionally, add a listener on port **80** with a rule to redirect HTTP traffic to HTTPS.
-3. Under **Security Groups**, create a security group that allows inbound traffic on **port 443**.
-4. Create a target group:
-    * **Target type**: Instance
-    * **Protocol**: HTTP
-    * **Port**: 80
-    * **Health check path**: `/api/v1/health`
-5. Register your EC2 instance as a target.
-6. Finish creating the ALB and wait for its status to become **Active**.
-
-### Create a DNS record
-
-1. In **Route 53** (or your DNS provider), create a DNS record:
-    - **Name**: `openops.your-company.com`
-    - **Type**: `A` (Alias) or `CNAME`
-    - **Value**: The DNS name of your ALB (for example, `openops-alb-123456789.us-east-1.elb.amazonaws.com`)
-2. Save and wait for DNS changes to propagate.
-
-### Update OpenOps configuration
-
-1. SSH into your EC2 instance or use CloudShell.
-2. Update the `.env` file to reflect your new domain:
-    ```env
-    OPS_PUBLIC_URL=https://openops.your-company.com
-    ```
-3. Restart the containers:
-    ```bash
-    sudo docker compose down && sudo docker compose up -d
-    ```
-
-### Troubleshooting
-
-If you encounter a 503 error:
-- Ensure you restarted Docker containers after updating `.env`.
-- Confirm that the ALB's health check is configured with the correct path (`/api/v1/health`).
-- Make sure the EC2 instance's security group allows traffic from the ALB.
-- Look for more cues in the Nginx container logs:
-    ```bash
-    sudo docker compose logs nginx
-    ```
-
-For more troubleshooting guidance, see [this AWS troubleshooting guide](https://repost.aws/knowledge-center/alb-troubleshoot-503-errors).
+<TLS target="EC2 instance"/>
 
 <UpdateLink/>
 

getting-started/deployment/azure-vm.mdx

@@ -6,6 +6,7 @@ icon: 'microsoft'
 
 import AutoInstall from '/snippets/auto-install.mdx'
 import Disclaimer from '/snippets/non-production-disclaimer.mdx';
+import TLS from '/snippets/tls.mdx';
 import UpdateCredentials from '/snippets/env-update-credentials.mdx';
 import UpdateLink from '/snippets/update-link.mdx';
 
@@ -81,11 +82,7 @@ You can now access the application by navigating to the public IP address of you
 
 See [this guide](https://docs.google.com/document/d/1WhwMk3he4d4vEv_7hIw7u_4ZIz_8ZewUS1yUKxpdYR0/edit?tab=t.0#heading=h.4lq77bkice4n).
 
-## TLS
-
-For production usage, it’s recommended to enable TLS (HTTPS). You can achieve this by adding an Azure Application Gateway to serve traffic to your VM.
-
-Without TLS, cloud templates may not load properly when using the Safari browser.
+<TLS target="VM"/>
 
 <UpdateLink/>
 

getting-started/deployment/gcp-vm.mdx

@@ -7,6 +7,7 @@ icon: 'google'
 import AutoInstall from '/snippets/auto-install.mdx'
 import Disclaimer from '/snippets/non-production-disclaimer.mdx';
 import RestartContainers from '/snippets/restart-containers.mdx';
+import TLS from '/snippets/tls.mdx';
 import UpdateCredentials from '/snippets/env-update-credentials.mdx';
 import UpdateLink from '/snippets/update-link.mdx';
 
@@ -115,11 +116,7 @@ If you remove or disable the `db` profile in `.env` or in Docker Compose, that c
 
 <RestartContainers/>
 
-## TLS
-
-For production usage, it’s recommended to serve the application over HTTPS. One way to achieve this on GCP is by using a HTTPS Load Balancer to terminate SSL/TLS and forward traffic to your VM. Alternatively, you can configure a TLS proxy or run a reverse proxy like Nginx with Certbot on your VM.
-
-Without TLS, some features (such as certain cloud templates) may not load properly in Safari.
+<TLS target="VM"/>
 
 <UpdateLink/>
 

snippets/tls.mdx

@@ -0,0 +1,16 @@
+## Enabling TLS
+
+For production usage, it’s recommended to enable TLS (HTTPS). In addition to the security aspect, this also ensures that [workflow templates](/workflow-management/workflow-templates/) load properly in all browsers.
+
+The easiest way to enable TLS is to use an OpenOps script that requests and sets up a TLS certificate from Let's Encrypt. Before running the script, make sure you have a domain name that points to your {target}'s external IP address. If you're configuring DNS right before running the script, you may need to wait for the DNS change to propagate.
+
+1. Run the following command in your terminal:
+    ```shell
+    curl -fsS https://openops.sh/tls | sh
+    ```
+2. When prompted, enter a domain name that points to the external IP address of your {target}.
+3. When prompted, enter an email address to receive certificate-related notifications from Let's Encrypt.
+
+The script will use the Certbot library to request a certificate for your domain from Let's Encrypt. It receives and saves the certificate, updates the OpenOps configuration file accordingly, and restarts OpenOps.
+
+By default, the certificate expires in 3 months. See https://certbot.org/renewal-setup if you want to configure auto-renewal.