Skip to content

Commit 736c663

Browse files
jpshackelfordopenhands-agent
jpshackelford
and
openhands-agent
authored
docs: add external PostgreSQL configuration guide (OpenHands#511)
* 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 <openhands@all-hands.dev> * 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 <openhands@all-hands.dev> * 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 <openhands@all-hands.dev> --------- Co-authored-by: openhands <openhands@all-hands.dev>
1 parent e71d383 commit 736c663

4 files changed

Lines changed: 122 additions & 0 deletions

File tree

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -439,6 +439,7 @@
439439
"enterprise/enterprise-vs-oss",
440440
"enterprise/quick-start",
441441
"enterprise/analytics",
442+
"enterprise/external-postgres",
442443
{
443444
"group": "K8s Install",
444445
"pages": [

‎enterprise/external-postgres.mdx‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
title: External PostgreSQL
3+
description: Configure OpenHands Enterprise to use your own PostgreSQL database
4+
icon: database
5+
---
6+
7+
OpenHands Enterprise can connect to an external PostgreSQL instance instead of using
8+
the bundled database. This is useful when you have existing database infrastructure,
9+
need specific backup/recovery procedures, or require high availability configurations.
10+
11+
## PostgreSQL Version
12+
13+
OpenHands Enterprise requires **PostgreSQL 16.4.0 or above**. PostgreSQL 17 is also supported.
14+
15+
## Required Databases
16+
17+
OpenHands Enterprise uses the following databases:
18+
19+
| Database | Purpose |
20+
|----------|---------|
21+
| `openhands` | Core application data |
22+
| `bitnami_keycloak` | Identity and access management |
23+
| `litellm` | LLM proxy configuration and usage tracking |
24+
| `runtime_api_db` | Runtime/sandbox management |
25+
| `automations` | Scheduled tasks and automation workflows |
26+
27+
## Database User Requirements
28+
29+
The PostgreSQL user provided to OpenHands Enterprise needs specific privileges depending
30+
on your preferred setup approach.
31+
32+
### Option 1: Automatic Database Creation (Recommended)
33+
34+
If you provide a database user with the `CREATEDB` privilege, OpenHands Enterprise will
35+
automatically create all required databases during installation.
36+
37+
```sql
38+
-- Create user with CREATEDB privilege
39+
CREATE USER openhands_user WITH PASSWORD 'your-secure-password' CREATEDB;
40+
```
41+
42+
When the user creates its own databases, it will automatically have all necessary privileges
43+
on them including the ability to manage the `public` schema.
44+
45+
### Option 2: Manual Database Creation
46+
47+
If your security policies prevent granting `CREATEDB`, you must manually create all
48+
databases before installation:
49+
50+
```sql
51+
-- Create the databases
52+
CREATE DATABASE openhands;
53+
CREATE DATABASE bitnami_keycloak;
54+
CREATE DATABASE litellm;
55+
CREATE DATABASE runtime_api_db;
56+
CREATE DATABASE automations;
57+
58+
-- Create user without CREATEDB
59+
CREATE USER openhands_user WITH PASSWORD 'your-secure-password';
60+
61+
-- Grant privileges on each database
62+
GRANT ALL PRIVILEGES ON DATABASE openhands TO openhands_user;
63+
GRANT ALL PRIVILEGES ON DATABASE bitnami_keycloak TO openhands_user;
64+
GRANT ALL PRIVILEGES ON DATABASE litellm TO openhands_user;
65+
GRANT ALL PRIVILEGES ON DATABASE runtime_api_db TO openhands_user;
66+
GRANT ALL PRIVILEGES ON DATABASE automations TO openhands_user;
67+
68+
-- Connect to each database and grant schema privileges
69+
\c openhands
70+
GRANT USAGE, CREATE ON SCHEMA public TO openhands_user;
71+
72+
\c bitnami_keycloak
73+
GRANT USAGE, CREATE ON SCHEMA public TO openhands_user;
74+
75+
\c litellm
76+
GRANT USAGE, CREATE ON SCHEMA public TO openhands_user;
77+
78+
\c runtime_api_db
79+
GRANT USAGE, CREATE ON SCHEMA public TO openhands_user;
80+
81+
\c automations
82+
GRANT USAGE, CREATE ON SCHEMA public TO openhands_user;
83+
```
84+
85+
## Network Requirements
86+
87+
Ensure your PostgreSQL instance is accessible from:
88+
89+
- The OpenHands application pods/services
90+
- The Keycloak service
91+
- The LiteLLM proxy service
92+
- The Runtime API service
93+
94+
If using network policies or firewalls, allow connections on the PostgreSQL port (default: 5432)
95+
from the OpenHands deployment.
96+
97+
## Configuration
98+
99+
When configuring OpenHands Enterprise, provide your external PostgreSQL connection details
100+
in the Admin Console or Helm values:
101+
102+
- **Host**: Your PostgreSQL server hostname or IP
103+
- **Port**: PostgreSQL port (default: 5432)
104+
- **Username**: The database user created above
105+
- **Password**: The user's password
106+
107+
<Note>
108+
For production deployments, we recommend enabling SSL/TLS for database connections.
109+
</Note>

‎enterprise/k8s-install/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,10 @@ OpenHands Enterprise consists of several components deployed as Kubernetes workl
5050

5151
## Guides
5252

53+
<Card title="External PostgreSQL" icon="database" href="/enterprise/external-postgres">
54+
Configure OpenHands to use your own PostgreSQL database instead of the bundled instance.
55+
</Card>
56+
5357
<Card title="Resource Limits" icon="gauge-high" href="/enterprise/k8s-install/resource-limits">
5458
Configure memory, CPU, and storage for optimal performance.
5559
</Card>

‎enterprise/quick-start.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,7 @@ All items below must be completed before running the installer:
148148
- Inbound ports are open: `80`, `443`, and `30000`
149149
- Outbound domains are reachable from the VM
150150
- GitHub App prerequisites are prepared
151+
- (Optional) [External PostgreSQL](/enterprise/external-postgres) instance provisioned if using your own database
151152

152153
<Warning>
153154
Do not run the installer until preflight checks pass.
@@ -330,6 +331,13 @@ You should now see the application configuration page.
330331

331332
Enter your Anthropic API key from the [Anthropic Console](https://console.anthropic.com/).
332333

334+
### Database Configuration
335+
336+
By default, OpenHands Enterprise uses a bundled PostgreSQL database. If you need to use your
337+
own PostgreSQL instance (for example, to integrate with existing database infrastructure or
338+
meet specific backup/HA requirements), see [External PostgreSQL](/enterprise/external-postgres)
339+
for setup instructions.
340+
333341
### GitHub Authentication
334342

335343
Enable GitHub Authentication in the Admin Console, then follow these steps to create and

0 commit comments

Comments
 (0)