From e08d0711179f6fe70c85c4723684fcb8495fb162 Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Mon, 26 Oct 2026 09:29:59 -0400 Subject: [PATCH 1/3] Add docker compose docs --- enterprise/docker-compose.mdx | 70 +++++++++++++++++++++ enterprise/docker-compose/https.mdx | 94 +++++++++++++++++++++++++++++ enterprise/docker-compose/ngrok.mdx | 56 +++++++++++++++++ 3 files changed, 220 insertions(+) create mode 100644 enterprise/docker-compose.mdx create mode 100644 enterprise/docker-compose/https.mdx create mode 100644 enterprise/docker-compose/ngrok.mdx diff --git a/enterprise/docker-compose.mdx b/enterprise/docker-compose.mdx new file mode 100644 index 000000000..9d3aa9d2a --- /dev/null +++ b/enterprise/docker-compose.mdx @@ -0,0 +1,70 @@ +--- +title: Docker Compose +description: Run OpenHands Enterprise with Docker Compose +icon: docker +--- + +The Docker Compose stack runs OpenHands Enterprise on a single machine. Use it to evaluate +OpenHands Enterprise with a small group of users. For production, we recommend +[Kubernetes](/enterprise/k8s-install/index). + +## Prerequisites + +- Git +- Docker and Docker Compose +- An API key from your LLM provider + +## Install + + + + ```bash + git clone https://github.com/OpenHands/enterprise.git + cd enterprise + docker compose up --wait + ``` + + The command returns when every service is healthy. On the first start the application pulls + images, which can take several minutes. + + + Open [http://localhost:3100](http://localhost:3100) and follow the onboarding flow to create + your first user and configure your LLM provider. + + + +## Share with your team + +By default, the stack is only reachable from the machine it runs on. To share it with others, +serve it over HTTPS with [ngrok](/enterprise/docker-compose/ngrok) or run it on a +[VM with your own domain](/enterprise/docker-compose/https). + +## Upgrade + +Pull the latest changes, then restart the stack: + +```bash +git pull +docker compose down +docker compose up --wait +``` + +The application migrates its database on startup. + +## Stop and reset + +Stop the stack with: + +```bash +docker compose down +``` + +Your data is stored in Docker volumes and is kept when you stop the stack. + +### Reset + +To delete all data and start over, stop any running sandbox containers, then remove the volumes: + +```bash +docker compose down -v +``` diff --git a/enterprise/docker-compose/https.mdx b/enterprise/docker-compose/https.mdx new file mode 100644 index 000000000..2978e3f1b --- /dev/null +++ b/enterprise/docker-compose/https.mdx @@ -0,0 +1,94 @@ +--- +title: Run on a VM with HTTPS +sidebarTitle: VM with HTTPS +description: Run the Docker Compose stack on a Linux VM and serve it over HTTPS at your own domain +icon: lock +--- + +This guide runs the [Docker Compose](/enterprise/docker-compose) stack on a Linux VM and serves it +over HTTPS at your own domain. Caddy handles HTTPS. Caddy can get a certificate from Let's Encrypt +automatically, or it can use a certificate that you provide. + +## Prerequisites + +- A Linux VM with at least 4 CPUs, 16 GB of memory, and 100 GB of disk +- [Docker Engine](https://docs.docker.com/engine/install/) with the Compose plugin, and Git +- A domain name for OpenHands, such as `openhands.example.com` +- Ports 80 and 443 open to your users +- An API key from your LLM provider + +## Install + + + + Create a DNS A record that points your domain to the IP address of the VM. + + + On the VM, run: + + ```bash + git clone https://github.com/OpenHands/enterprise.git + cd enterprise + ``` + + + Create a `.env` file in the `enterprise` directory. Replace `openhands.example.com` with your + domain. + + + + ```bash .env + COMPOSE_FILE=docker-compose.yml:docker-compose.https.yml + WEB_HOST=openhands.example.com + WEB_URL=https://openhands.example.com + AGENT_CANVAS_LOCK_TO_CLOUD=https://openhands.example.com + ``` + + Caddy gets a certificate from Let's Encrypt when the stack starts and renews it + automatically. Let's Encrypt must be able to reach the VM from the internet on port 80 or + 443. + + + ```bash .env + COMPOSE_FILE=docker-compose.yml:docker-compose.https-own-cert.yml + WEB_HOST=openhands.example.com + WEB_URL=https://openhands.example.com + AGENT_CANVAS_LOCK_TO_CLOUD=https://openhands.example.com + ``` + + Copy your certificate and private key into the `certs` directory: + + ```bash + mkdir -p certs + cp /path/to/fullchain.pem certs/cert.pem + cp /path/to/privkey.pem certs/key.pem + ``` + + The certificate must be issued by a public certificate authority, and `cert.pem` must + contain the full certificate chain. + + + + `COMPOSE_FILE` adds a Caddy service that serves HTTPS on ports 80 and 443. Docker Compose + reads this file on every command, so the commands on the + [Docker Compose](/enterprise/docker-compose) page work without changes. + + + ```bash + docker compose up --wait + ``` + + + Open `https://openhands.example.com` and follow the onboarding flow to create your first user + and configure your LLM provider. + + + +## Replace Your Certificate + +If you use your own certificate, copy the new files to `certs/cert.pem` and `certs/key.pem`, then +restart Caddy: + +```bash +docker compose restart https +``` diff --git a/enterprise/docker-compose/ngrok.mdx b/enterprise/docker-compose/ngrok.mdx new file mode 100644 index 000000000..97bbd29cf --- /dev/null +++ b/enterprise/docker-compose/ngrok.mdx @@ -0,0 +1,56 @@ +--- +title: Serve with ngrok +sidebarTitle: ngrok +description: Give the Docker Compose stack a public HTTPS URL with ngrok +icon: globe +--- + +Use ngrok to give the [Docker Compose](/enterprise/docker-compose) stack a public HTTPS URL. You +don't need to open any ports. + +## Prerequisites + +- The [Docker Compose prerequisites](/enterprise/docker-compose#prerequisites) +- ngrok, installed and connected to your ngrok account. Follow steps 1 and 2 of the + [ngrok Agent CLI Quickstart](https://ngrok.com/docs/gateway/endpoints/agent-cli-quickstart). +- Your ngrok domain. Every ngrok account includes a free dev domain, such as + `example-name.ngrok-free.app`. You can find it on the [Domains](https://dashboard.ngrok.com/domains) + page of the ngrok dashboard. + +## Install + + + + ```bash + git clone https://github.com/OpenHands/enterprise.git + cd enterprise + ``` + + + Create a `.env` file in the `enterprise` directory. Replace `example-name.ngrok-free.app` with + your ngrok domain: + + ```bash .env + WEB_HOST=example-name.ngrok-free.app + WEB_URL=https://example-name.ngrok-free.app + AGENT_CANVAS_LOCK_TO_CLOUD=https://example-name.ngrok-free.app + ``` + + + ```bash + docker compose up --wait + ``` + + + ```bash + ngrok http 3100 --url https://example-name.ngrok-free.app + ``` + + ngrok serves the stack at your domain while this command runs. Keep it running. + + + Open your ngrok URL and follow the onboarding flow to create your first user and configure + your LLM provider. On a free ngrok account, ngrok shows a warning page first. Click **Visit** + to continue. + + From e18477f7d2f481fd4853c773a183cef3a1bc70ed Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Mon, 26 Oct 2026 11:48:49 -0400 Subject: [PATCH 2/3] Update docker compose port to 9043 --- enterprise/docker-compose.mdx | 2 +- enterprise/docker-compose/ngrok.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/enterprise/docker-compose.mdx b/enterprise/docker-compose.mdx index 9d3aa9d2a..c6ec73625 100644 --- a/enterprise/docker-compose.mdx +++ b/enterprise/docker-compose.mdx @@ -28,7 +28,7 @@ OpenHands Enterprise with a small group of users. For production, we recommend images, which can take several minutes. - Open [http://localhost:3100](http://localhost:3100) and follow the onboarding flow to create + Open [http://localhost:9043](http://localhost:9043) and follow the onboarding flow to create your first user and configure your LLM provider. diff --git a/enterprise/docker-compose/ngrok.mdx b/enterprise/docker-compose/ngrok.mdx index 97bbd29cf..f6461660b 100644 --- a/enterprise/docker-compose/ngrok.mdx +++ b/enterprise/docker-compose/ngrok.mdx @@ -43,7 +43,7 @@ don't need to open any ports. ```bash - ngrok http 3100 --url https://example-name.ngrok-free.app + ngrok http 9043 --url https://example-name.ngrok-free.app ``` ngrok serves the stack at your domain while this command runs. Keep it running. From edacfd4087424243024ed4f398289489b2ee7c16 Mon Sep 17 00:00:00 2001 From: Joe Laverty Date: Mon, 26 Oct 2026 14:18:43 -0400 Subject: [PATCH 3/3] Update enterprise/docker-compose.mdx Co-authored-by: aivong-openhands --- enterprise/docker-compose.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/enterprise/docker-compose.mdx b/enterprise/docker-compose.mdx index c6ec73625..7cebb27f9 100644 --- a/enterprise/docker-compose.mdx +++ b/enterprise/docker-compose.mdx @@ -24,7 +24,7 @@ OpenHands Enterprise with a small group of users. For production, we recommend docker compose up --wait ``` - The command returns when every service is healthy. On the first start the application pulls + The command returns when every service is healthy. On the first start, the application pulls images, which can take several minutes.