Problem
When installing or upgrading the Univention Keycloak App with an external PostgreSQL database configured (e.g. via kc/db/url), the process aborts with an error similar to:
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed:
No such file or directory
Is the server running locally and accepting connections on that socket?
Returncode 2 for query
Aborting...
This occurs even though:
- A valid external database connection is configured
- The external PostgreSQL server is reachable
- Credentials are correct
The issue can appear during:
- Initial installation (
univention-app install keycloak) - Upgrade (
univention-app upgrade keycloak)
Investigation
The Keycloak App supports the use of an external PostgreSQL database as documented in the official documentation:
- Keycloak App Database Configuration – After Initial Installation
However, during installation and upgrade, multiple components are involved:
1. Pre-installation scripts (preinst)
- In upgrade scenarios, database checks may use Python (
psycopg2) and correctly connect to the configured external database. - In new installations, the scripts do not have access to the configured app settings (
kc/db/*) and therefore assume a local PostgreSQL instance.
2. Univention App Center lifecycle
Independent of the Keycloak configuration, the App Center performs additional checks and setup tasks, including:
- Verifying database existence
- Creating users or databases if required
- Running SQL queries via
psql
These commands are executed without specifying a remote host, which results in attempts to connect via the local UNIX socket:
/var/run/postgresql/.s.PGSQL.5432
3. Mixed database access methods
| Component | Database Access |
|---|---|
| Keycloak runtime | External DB (via JDBC URL) |
Python checks (psycopg2) |
External DB (upgrade only) |
App Center scripts (psql, createdb, createuser) |
Local DB (socket) |
| UCR templates (PostgreSQL config) | Local DB |
This inconsistency leads to failures when no local PostgreSQL server is available.
Root Cause
The issue is caused by a design inconsistency in the Keycloak App and the Univention App Center lifecycle.
While the application itself supports external PostgreSQL databases, the installation and upgrade routines still assume the presence of a locally running PostgreSQL instance for internal checks and setup operations.
This behavior is tracked in the following bug report:
The App Center and related scripts are not fully external-database-aware and continue to use local PostgreSQL tools (
psql,createdb, etc.) without considering the configured external database.
Workaround
Ensure that a local PostgreSQL instance is available during installation or upgrade.
1. Start the local PostgreSQL cluster
If PostgreSQL is already installed but not running, start it manually:
pg_ctlcluster 15 main start
Alternatively, ensure the service is running:
systemctl start postgresql
2. Perform installation or upgrade
univention-app install keycloak
# or
univention-app upgrade keycloak
After starting the local PostgreSQL instance, the Keycloak installation or upgrade proceeds successfully.
3. Stop the local PostgreSQL cluster (optional)
If the local database is not required after installation or upgrade, it can be stopped again:
pg_ctlcluster 15 main stop
or via systemd:
systemctl stop postgresql
Summary
- The Keycloak App supports external PostgreSQL databases at runtime.
- Installation and upgrade procedures still rely on a local PostgreSQL instance.
- A local PostgreSQL service must be available to ensure successful execution of App Center scripts.
- Starting the local cluster (e.g. via
pg_ctlcluster) resolves the issue. - The local service can be stopped again after the process if not needed.
- This limitation is tracked in Bug 58720 and may be addressed in future releases.