From 0e7f320675717591f09cb02c0a2b07c4bafd5d42 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 19 May 2026 17:40:47 +0000 Subject: [PATCH 1/3] docs: add external PostgreSQL configuration guide Add documentation for customers using their own PostgreSQL instance instead of the bundled database. Includes: - PostgreSQL version requirements (16.4.0+) - Required databases (openhands, bitnami_keycloak, litellm, runtime_api_db, automations) - User privilege requirements (CREATEDB for auto-creation, or manual setup) - Schema permissions needed (USAGE, CREATE on public) Co-authored-by: openhands --- docs.json | 1 + enterprise/external-postgres.mdx | 110 +++++++++++++++++++++++++++++++ enterprise/k8s-install/index.mdx | 4 ++ 3 files changed, 115 insertions(+) create mode 100644 enterprise/external-postgres.mdx diff --git a/docs.json b/docs.json index 849783d52..52134ec4e 100644 --- a/docs.json +++ b/docs.json @@ -439,6 +439,7 @@ "enterprise/enterprise-vs-oss", "enterprise/quick-start", "enterprise/analytics", + "enterprise/external-postgres", { "group": "K8s Install", "pages": [ diff --git a/enterprise/external-postgres.mdx b/enterprise/external-postgres.mdx new file mode 100644 index 000000000..c8d03fb86 --- /dev/null +++ b/enterprise/external-postgres.mdx @@ -0,0 +1,110 @@ +--- +title: External PostgreSQL +description: Configure OpenHands Enterprise to use your own PostgreSQL database +icon: database +--- + +OpenHands Enterprise can connect to an external PostgreSQL instance instead of using +the bundled database. This is useful when you have existing database infrastructure, +need specific backup/recovery procedures, or require high availability configurations. + +## PostgreSQL Version + +OpenHands Enterprise requires **PostgreSQL 16.4.0 or above**. PostgreSQL 17 is also supported. + +## Required Databases + +OpenHands Enterprise uses the following databases: + +| Database | Purpose | +|----------|---------| +| `openhands` | Core application data | +| `bitnami_keycloak` | Identity and access management | +| `litellm` | LLM proxy configuration and usage tracking | +| `runtime_api_db` | Runtime/sandbox management | +| `automations` | Scheduled tasks and automation workflows | + +## Database User Requirements + +The PostgreSQL user provided to OpenHands Enterprise needs specific privileges depending +on your preferred setup approach. + +### Option 1: Automatic Database Creation (Recommended) + +If you provide a database user with the `CREATEDB` privilege, OpenHands Enterprise will +automatically create all required databases during installation. + +```sql +-- Create user with CREATEDB privilege +CREATE USER openhands_user WITH PASSWORD 'your-secure-password' CREATEDB; +``` + +The user also needs permission to grant `USAGE` and `CREATE` on the `public` schema. + +### Option 2: Manual Database Creation + +If your security policies prevent granting `CREATEDB`, you must manually create all +databases before installation: + +```sql +-- Create the databases +CREATE DATABASE openhands; +CREATE DATABASE bitnami_keycloak; +CREATE DATABASE litellm; +CREATE DATABASE runtime_api_db; +CREATE DATABASE automations; + +-- Create user without CREATEDB +CREATE USER openhands_user WITH PASSWORD 'your-secure-password'; + +-- Grant privileges on each database +GRANT ALL PRIVILEGES ON DATABASE openhands TO openhands_user; +GRANT ALL PRIVILEGES ON DATABASE bitnami_keycloak TO openhands_user; +GRANT ALL PRIVILEGES ON DATABASE litellm TO openhands_user; +GRANT ALL PRIVILEGES ON DATABASE runtime_api_db TO openhands_user; +GRANT ALL PRIVILEGES ON DATABASE automations TO openhands_user; + +-- Connect to each database and grant schema privileges +\c openhands +GRANT USAGE, CREATE ON SCHEMA public TO openhands_user; + +\c bitnami_keycloak +GRANT USAGE, CREATE ON SCHEMA public TO openhands_user; + +\c litellm +GRANT USAGE, CREATE ON SCHEMA public TO openhands_user; + +\c runtime_api_db +GRANT USAGE, CREATE ON SCHEMA public TO openhands_user; + +\c automations +GRANT USAGE, CREATE ON SCHEMA public TO openhands_user; +``` + +## Network Requirements + +Ensure your PostgreSQL instance is accessible from: + +- The OpenHands application pods/services +- The Keycloak service +- The LiteLLM proxy service +- The Runtime API service + +If using network policies or firewalls, allow connections on the PostgreSQL port (default: 5432) +from the OpenHands deployment. + +## Configuration + +When configuring OpenHands Enterprise, provide your external PostgreSQL connection details +in the Admin Console or Helm values: + +- **Host**: Your PostgreSQL server hostname or IP +- **Port**: PostgreSQL port (default: 5432) +- **Username**: The database user created above +- **Password**: The user's password +- **SSL Mode**: Configure based on your security requirements + + + For production deployments, we recommend enabling SSL/TLS for database connections + and using a connection pooler like PgBouncer for improved performance. + diff --git a/enterprise/k8s-install/index.mdx b/enterprise/k8s-install/index.mdx index db70d66a8..50b7fdd31 100644 --- a/enterprise/k8s-install/index.mdx +++ b/enterprise/k8s-install/index.mdx @@ -50,6 +50,10 @@ OpenHands Enterprise consists of several components deployed as Kubernetes workl ## Guides + + Configure OpenHands to use your own PostgreSQL database instead of the bundled instance. + + Configure memory, CPU, and storage for optimal performance. From 4d5fcc1488bae811bc695c97e523e2794441758b Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 19 May 2026 18:00:10 +0000 Subject: [PATCH 2/3] docs: add links to external PostgreSQL from quick-start - Add optional external PostgreSQL to preflight checklist - Add Database Configuration section in Configure OpenHands Co-authored-by: openhands --- enterprise/quick-start.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 7c0f33e65..dbabf4d0c 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -148,6 +148,7 @@ All items below must be completed before running the installer: - Inbound ports are open: `80`, `443`, and `30000` - Outbound domains are reachable from the VM - GitHub App prerequisites are prepared +- (Optional) [External PostgreSQL](/enterprise/external-postgres) instance provisioned if using your own database Do not run the installer until preflight checks pass. @@ -330,6 +331,13 @@ You should now see the application configuration page. Enter your Anthropic API key from the [Anthropic Console](https://console.anthropic.com/). +### Database Configuration + +By default, OpenHands Enterprise uses a bundled PostgreSQL database. If you need to use your +own PostgreSQL instance (for example, to integrate with existing database infrastructure or +meet specific backup/HA requirements), see [External PostgreSQL](/enterprise/external-postgres) +for setup instructions. + ### GitHub Authentication Enable GitHub Authentication in the Admin Console, then follow these steps to create and From 2362864ce52bbc98577e9430ac96a1f577095e58 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 19 May 2026 19:36:26 +0000 Subject: [PATCH 3/3] docs: address Joe's review feedback - Clarify CREATEDB privilege explanation (user auto-has privileges on DBs it creates) - Remove SSL Mode config option (replicated installer doesn't support disabling SSL) - Remove PgBouncer recommendation (no operational experience with it) Co-authored-by: openhands --- enterprise/external-postgres.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/enterprise/external-postgres.mdx b/enterprise/external-postgres.mdx index c8d03fb86..76126aac2 100644 --- a/enterprise/external-postgres.mdx +++ b/enterprise/external-postgres.mdx @@ -39,7 +39,8 @@ automatically create all required databases during installation. CREATE USER openhands_user WITH PASSWORD 'your-secure-password' CREATEDB; ``` -The user also needs permission to grant `USAGE` and `CREATE` on the `public` schema. +When the user creates its own databases, it will automatically have all necessary privileges +on them including the ability to manage the `public` schema. ### Option 2: Manual Database Creation @@ -102,9 +103,7 @@ in the Admin Console or Helm values: - **Port**: PostgreSQL port (default: 5432) - **Username**: The database user created above - **Password**: The user's password -- **SSL Mode**: Configure based on your security requirements - For production deployments, we recommend enabling SSL/TLS for database connections - and using a connection pooler like PgBouncer for improved performance. + For production deployments, we recommend enabling SSL/TLS for database connections.