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..76126aac2
--- /dev/null
+++ b/enterprise/external-postgres.mdx
@@ -0,0 +1,109 @@
+---
+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;
+```
+
+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
+
+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
+
+
+ For production deployments, we recommend enabling SSL/TLS for database connections.
+
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.
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