From e9d1fe291c0c046b54f2f5c04481c7bd95ac3f08 Mon Sep 17 00:00:00 2001 From: Vittorio Esposito Date: Wed, 22 Jul 2026 08:24:27 +0200 Subject: [PATCH] docs: document self-signed CA trust for database SSL --- content/configuration/database.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/content/configuration/database.md b/content/configuration/database.md index be76d456..7f4f6452 100644 --- a/content/configuration/database.md +++ b/content/configuration/database.md @@ -34,3 +34,28 @@ This includes: **Note** `DB_SSL__CA_FILE` may be preferred to load the CA directly from a file. :: + +## Self-Signed Certificates + +Managed databases (for example Heroku Managed PostgreSQL or DigitalOcean Managed PostgreSQL) often enforce SSL and provide their own Certificate Authority (CA). Because that CA is not in Node.js' default trust store, connections can fail with `SELF_SIGNED_CERT_IN_CHAIN`. + +PostgreSQL connection-string options such as `sslmode=verify-full` are interpreted by `libpq` / `psql`, not by the Node.js PostgreSQL driver used by Directus. Prefer the `DB_SSL__*` variables below (or `NODE_EXTRA_CA_CERTS`) instead of relying on `sslmode` in `DB_CONNECTION_STRING`. + +To trust the provider CA while still verifying certificates: + +1. Download the database CA certificate in PEM format. +2. Point Directus at that certificate with either: + - `DB_SSL__CA_FILE` — absolute path to the PEM file (preferred), or + - `DB_SSL__CA` — PEM contents as a string +3. Keep certificate verification enabled (`DB_SSL__REJECT_UNAUTHORIZED` unset or `true`). + +Alternatively, add the CA to the Node.js trust store for the whole process: + +``` +NODE_EXTRA_CA_CERTS="/absolute/path/to/db-ca.crt" +``` + +::callout{icon="i-lucide-triangle-alert" color="warning"} +**Warning** +Do not set `DB_SSL__REJECT_UNAUTHORIZED`, `rejectUnauthorized`, or `NODE_TLS_REJECT_UNAUTHORIZED` to `false` in production. That disables TLS certificate verification and weakens the security of the entire application. Prefer trusting the provider CA with `DB_SSL__CA_FILE` / `DB_SSL__CA` or `NODE_EXTRA_CA_CERTS`. +::