Healthcheck of db_postgress failed when using docker compose to deploy dify

[youyexcd]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

I was trying to deploy dify using docker compose according to the quick-start guid.
cd dify/docker
cp .env.example .env
docker compose up -d

health check for db_postgress service was failed.
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
dify-db_postgres-1 postgres:15-alpine "docker-entrypoint.s…" db_postgres 4 minutes ago Up 4 minutes (unhealthy) 0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp

would you please help if any steps I missed ?

2. Additional context or comments

[dosubot[bot]]

Hi @youyexcd! I'm Dosu and I’m helping the dify team.

The db_postgres healthcheck failure in Dify's Docker Compose setup is usually caused by one or more of these issues:

• The Docker Compose file includes unsupported required: false lines under depends_on. Docker Compose v3+ does not support this property, which causes containers to stay in the "created" state and not start. Remove all required: false lines from every depends_on section in docker-compose-template.yaml, then regenerate docker-compose.yaml and restart your stack. See details and step-by-step fix here.
• The .env file has a mismatch for DB_HOST. It must be set to db_postgres to match the service name in the compose file. If it's set to db or anything else, the healthcheck and other services can't connect to the database, causing failures. See this example.
• The healthcheck command for db_postgres uses pg_isready but does not supply a password. If your PostgreSQL is set up with a password (the default), this can cause authentication failures. You may need to adjust the healthcheck to include the password, e.g., by setting PGPASSWORD in the environment or prepending it to the command. See the compose config here.
• Volume mount permission issues can prevent PostgreSQL from initializing. Make sure ./volumes/db/data exists and is writable by Docker. On macOS, you may need to adjust permissions or use Docker Desktop's file sharing settings. See troubleshooting tips here.
• The db_postgres service is only included if you use the postgresql profile. Start your stack with docker compose --profile postgresql up -d or set COMPOSE_PROFILES=postgresql in your environment reference.

After making these changes, restart your containers. If the healthcheck still fails, run docker compose logs db_postgres and check for specific errors—these logs will help pinpoint any remaining issues.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[youyexcd]

Hi, @dosu
I think it is the problem of DB_HOST.
I have check the DB_HOST in .env, it's db_postgres

Then I login into db_postgres container, using postgres ,below is the result

# docker compose exec db_postgres bash
6adf574c23a2:/# su postgres
/ $ id
uid=70(postgres) gid=70(postgres) groups=70(postgres),70(postgres)
/ $ ps -ef | grep isready
 1603 root      0:00 pg_isready -h db_postgres -U postgres -d dify
 1611 postgres  0:00 grep isready
/ $ pg_isready -U postgres -d dify
/var/run/postgresql:5432 - accepting connections
/ $ pg_isready -h db_postgres -U postgres -d dify
db_postgres:5432 - no response

Does it mean DB_HOST db_postgres could not be resolved？

[dosubot[bot]]

The reason pg_isready -h db_postgres fails inside the container is that PostgreSQL is only listening on localhost and the Unix socket by default, not on the container's network interface. To fix this, add -c listen_addresses=0.0.0.0 to the command section of the db_postgres service in your docker-compose.yaml (or docker-compose-template.yaml if you use templates), so it looks like:

command: >
  postgres -c 'max_connections=100'
           -c 'shared_buffers=128MB'
           ...
           -c 'listen_addresses=0.0.0.0'

Then restart the container. This will allow TCP connections to db_postgres and should make the healthcheck pass. If you still see issues, check the logs with docker compose logs db_postgres for permission or authentication errors, and make sure your data volume is writable and owned by the postgres user. If you see authentication errors for Docker network IPs, you may need to update pg_hba.conf to allow connections from the Docker bridge network (e.g., add host all all 172.18.0.0/16 md5) and restart the container.

Reference: docker-compose.yaml config

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[youyexcd]

I tried to add -c 'listen_addresses=0.0.0.0' to the command section of the db_postgres service in your docker-compose.yaml, but still not work. It was still failed in pg_isready -h db_postgres -U postgres -d dify, the hostname was not resolved yet.
I did another 2 test:

1. When I try to remove -h db_postgres from healthcheck/test section of the db_postgress service, then restart container, health check worked.

  db_postgres:
    image: postgres:15-alpine
    ...
    healthcheck:
      test:
        [
          "CMD",
          "pg_isready",
          "-U",
          "${DB_USERNAME:-postgres}",
          "-d",
          "${DB_DATABASE:-dify}",
        ]

2. When I add hostname: ${DB_HOST:-db_postgres} to db_postgres service , and keep -h db_postgress in test section, it works too.

  db_postgres:
    image: postgres:15-alpine
    ...
    hostname: ${DB_HOST:-db_postgres}
    ...
    healthcheck:
      test:
        [
          "CMD",
          "pg_isready",
          "-h",
          "db_postgres",
          "-U",
          "${DB_USERNAME:-postgres}",
          "-d",
          "${DB_DATABASE:-dify}",
        ]

In all cases , the .evn file was not changed. The parameter DB_HOST was alway db_postgres.
@dosu