docs: add external PostgreSQL configuration guide #511
+122
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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; | ||
| ``` | ||
|
Comment on lines
+50
to
+83
Contributor
There was a problem hiding this comment. 🟡 Suggestion: Consider adding important PostgreSQL best practices for enterprise deployments:
Example addition after line 82: -- (Optional) Set connection limits if needed
ALTER USER openhands_user CONNECTION LIMIT 100;
-- Verify the setup
\l openhands -- Should show all 5 databases with openhands_user as owner or grantee |
||
|
|
||
| ## 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. | ||
|
Comment on lines
+85
to
+95
Contributor
There was a problem hiding this comment. 🟡 Suggestion: Add clarity about which services connect to which databases. Currently, it's unclear if:
Consider adding a table: | Service | Database(s) Used |
|---------|------------------|
| OpenHands Server | `openhands`, `automations` |
| Keycloak | `bitnami_keycloak` |
| LiteLLM Proxy | `litellm` |
| Runtime API | `runtime_api_db` | |
||
|
|
||
| ## 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 | ||
|
|
||
| <Note> | ||
| For production deployments, we recommend enabling SSL/TLS for database connections. | ||
| </Note> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡 Suggestion: Be more specific about version requirements. Is 16.4.0 a hard requirement, or will 16.0-16.3 work? If there's a specific reason for 16.4.0 (e.g., a critical bug fix or required feature), briefly mention it:
If earlier 16.x versions are actually fine, adjust accordingly.