Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The postgres container exits when ssl=on and a mounted certificate

ErrorPostgres unable to load ssl certificate

Short answer

With ssl=on, PostgreSQL refuses to start if it cannot use the certificate and key. In a container that goes wrong in three ways: the files are not where the server looks, the key's owner or mode is wrong as the container sees it, or the key has a passphrase that nobody can type. Check the files from inside.

  • Applies to PostgreSQL 17, postgres Docker image 17, Docker Engine 28, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the log of the failed start, then list the certificate files as the container sees them, with numeric owner IDs. A one-off container is used because the real one keeps exiting.

    docker compose logs db --tail 20
    docker compose run --rm --no-deps --entrypoint sh db -c "id postgres; ls -ln /certs"
  2. 2Match what you see, then jump to its fix

    1. 1The log names server.crt or server.key without a path, and your files are mounted somewhere elseThe server looks for server.crt and server.key in the data directoryFix
    2. 2The key is listed with a numeric owner that is not the postgres user, and a mode more open than 0600The key's owner or permissions are wrong inside the containerFix
    3. 3The container stops with no error about permissions, and the key file contains the word ENCRYPTEDThe private key is protected by a passphraseFix

What does the error look like?

  • Postgres unable to load ssl certificate
  • the container exits a second after docker compose up, and the log names server.crt or server.key

Cause 1 of 3

The server looks for server.crt and server.key in the data directory

1Check

By default PostgreSQL expects files called server.crt and server.key in its data directory. Other names and places have to be set with ssl_cert_file and ssl_key_file. Compare the volumes of the service with the paths the server is told to use.

docker compose config | grep -n -E "command:|ssl|/certs|volumes:"

2Fix

Mount the files outside the data directory and pass the settings on the command line, which the image passes on to the server.

services:
  db:
    image: postgres:17
    environment:
      POSTGRES_PASSWORD: change-me-example
    volumes:
      - ./certs:/certs:ro
    command: >
      postgres
      -c ssl=on
      -c ssl_cert_file=/certs/server.crt
      -c ssl_key_file=/certs/server.key

3Verify

Start the stack and ask the server whether SSL is on.

docker compose up -d db
docker compose exec db psql -U postgres -c "SHOW ssl;"

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

The key's owner or permissions are wrong inside the container

1Check

On Unix, the key must disallow any access to group and world. That means mode 0600 owned by the user the server runs as, or owned by root with 0640 and the server user in that file's group. Compare the uid printed by id postgres with the owner and mode in the listing.

docker compose run --rm --no-deps --entrypoint sh db -c "id postgres; ls -ln /certs/server.key"

2Fix

On a Linux host, give the key file to the ids that id postgres printed and set mode 0600. If the host cannot set the owner, build a small image for a test certificate with COPY --chown and --chmod; numeric ids need no user lookup during the build, and the ./certs mount is then not needed. Never push an image that holds a production key.

# on the Linux host, with the ids printed by id postgres
sudo chown <uid>:<gid> certs/server.key
chmod 600 certs/server.key

# or, for a test certificate only: Dockerfile
FROM postgres:17
COPY --chown=<uid>:<gid> --chmod=600 certs/server.key /certs/server.key
COPY certs/server.crt /certs/server.crt

3Verify

The listing now shows the postgres ids and -rw-------, and the server starts.

docker compose run --rm --no-deps --entrypoint sh db -c "ls -ln /certs"

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The private key is protected by a passphrase

1Check

A key with a passphrase makes the server prompt for it, and it does not start until the passphrase is entered. A container has no one to type it.

grep -c ENCRYPTED certs/server.key

2Fix

Create the key without a passphrase, as the manual's openssl example does with -nodes, or give the server a passphrase command through ssl_passphrase_command. For a local test certificate the manual's command is enough.

openssl req -new -x509 -days 365 -nodes -text -out certs/server.crt \
  -keyout certs/server.key -subj "/CN=dbhost.example.com"
chmod og-rwx certs/server.key

3Verify

Rebuild or restart the service. The log shows no prompt and the container stays up.

docker compose up -d --build db
docker compose ps db

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Keep certificate and key outside the data directory and name both files in -c options, so nothing depends on the default file names.
  • Check the owner and mode of the key from inside the container whenever you change how it is delivered.
  • Use a real certificate from your certificate authority in production; the openssl example is for tests.
  • Remember that a bad file stops the server at start, while a bad file during a configuration reload is ignored and the old setting stays.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.