docs: add external PostgreSQL configuration guide#511
Merged
Conversation
Contributor
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Documentation provides good coverage of external PostgreSQL setup, but needs clarification on specific privilege requirements and configuration details to ensure customers can successfully complete the setup.
|
|
||
| ## PostgreSQL Version | ||
|
|
||
| OpenHands Enterprise requires **PostgreSQL 16.4.0 or above**. PostgreSQL 17 is also supported. |
Contributor
There was a problem hiding this comment.
🟡 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:
Suggested change
| OpenHands Enterprise requires **PostgreSQL 16.4.0 or above**. PostgreSQL 17 is also supported. | |
| OpenHands Enterprise requires **PostgreSQL 16.4.0 or later**. PostgreSQL 17 is also supported. |
If earlier 16.x versions are actually fine, adjust accordingly.
Comment on lines
+97
to
+105
|
|
||
| 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 |
Contributor
There was a problem hiding this comment.
🟠 Important: This section lists configuration fields but doesn't specify HOW to provide them. Enterprise customers need concrete guidance.
Add specific details:
- What are the actual Helm value names? (e.g.,
postgresql.external.host,postgresql.external.port?) - If using Admin Console, what section/page are these fields in?
- Is there a single connection string, or separate credentials per service?
Suggestion: Add a subsection with actual Helm values example or Admin Console screenshot reference:
### Helm Values
When deploying via Helm, configure the external PostgreSQL connection in your `values.yaml`:
```yaml
postgresql:
external:
enabled: true
host: "your-postgres-host"
port: 5432
username: "openhands_user"
password: "your-secure-password"
sslMode: "require"Admin Console
When using the Admin Console, navigate to Settings → Database and configure the external PostgreSQL connection.
(Adjust field names to match actual implementation)
Comment on lines
+84
to
+94
| ## 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. |
Contributor
There was a problem hiding this comment.
🟡 Suggestion: Add clarity about which services connect to which databases. Currently, it's unclear if:
- Each service connects only to its designated database (e.g., Keycloak → bitnami_keycloak only)
- All services share the same database user credentials
- Network policies need to allow all pods to all databases or specific mappings exist
Consider adding a table:
| Service | Database(s) Used |
|---------|------------------|
| OpenHands Server | `openhands`, `automations` |
| Keycloak | `bitnami_keycloak` |
| LiteLLM Proxy | `litellm` |
| Runtime API | `runtime_api_db` |
Comment on lines
+49
to
+82
| ```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; | ||
| ``` |
Contributor
There was a problem hiding this comment.
🟡 Suggestion: Consider adding important PostgreSQL best practices for enterprise deployments:
- Database encoding: Should databases be created with UTF8 encoding?
- User security: Explicitly recommend NOT using a superuser
- Connection limits: Any per-database or per-user connection limits to consider?
- Verification step: How to test that the setup is correct before installation?
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
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>
jpshackelford
force-pushed
the
docs/external-postgres-requirements
branch
from
a1482b6 to
0e7f320
Compare
- Add optional external PostgreSQL to preflight checklist - Add Database Configuration section in Configure OpenHands Co-authored-by: openhands <openhands@all-hands.dev>
jlav
reviewed
May 19, 2026
jlav
reviewed
May 19, 2026
jlav
approved these changes
May 19, 2026
Contributor
jlav
left a comment
jlav
left a comment
There was a problem hiding this comment.
I left a couple of comments for cleanup, but overall looks good.
- 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>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
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.
Summary
Add documentation for customers deploying OpenHands Enterprise with their own external PostgreSQL instance instead of the bundled database.
Changes
New page:
enterprise/external-postgres.mdx— Comprehensive guide covering:openhands,bitnami_keycloak,litellm,runtime_api_db,automationsCREATEDBprivilegeUpdated
enterprise/k8s-install/index.mdx— Added card linking to the new external PostgreSQL guideUpdated
docs.json— Added navigation entry for the new pageContext
This information was gathered from internal discussions about customer requirements for external PostgreSQL setup (specifically for customers who need to use their existing database infrastructure rather than the bundled PostgreSQL).
This PR was created by an AI agent (OpenHands) on behalf of John-Mason Shackelford.
@jpshackelford can click here to continue refining the PR