Skip to content

DB setup for production

Jump to bottom
vukilelanga edited this page Feb 26, 2026 · 1 revision

For production instances, docker-compose will not start a database container. You need to supply your own postgresql DB, either on the same host as your docker containers or a separate host.

When setting up a postgresql DB for production, ensure that the following steps are done:

  1. Ensure postgres has a database available for kotahi, with an appropriate user set up as owner. The database name, user name and user password need to be configured in the .env file (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB). Also configure (POSTGRES_HOST and POSTGRES_PORT).
  2. postgresql.conf should have listen_addresses set to either '*' (less secure) or the specific IP address of the host interface that Docker can reach (more secure).
  3. If postgres is running on the same host as the docker containers, pg_hba.conf should contain an entry allowing connections from host all all 172.17.0.0/16 md5 (substituting your actual docker range, which you can find by running ip addr from within a docker container, look for the eth0 entry's inet value, e.g. 172.17.0.2/16, and change the last digit of the IP to 0, e.g. 172.17.0.0/16).
  4. If running postgres remotely, pg_hba.conf needs an entry host all all 192.168.12.34/32 md5 (substituting the host interface that your docker containers run on / can reach). In some cases this appears to be needed even when the containers and postgres are on the same host!
  5. In both these cases, you can make the pg_hba.conf entries more secure by restricting to a specific user/database, e.g. host mydb myuser 172.17.0.0/16 md5.
  6. Make sure postgres is restarted to apply changes. Rebuild Kotahi if you've changed the .env file.

Troubleshooting:

  1. From inside your server container, attempt to connect to the DB using psql: psql -h <host> -p <port> -U <db-username> -d <db-database>. (To enter the server container if it has stopped, you can list all images using docker ps, find the server container's image name, then run the server interactively using docker run -it <server-image> /bin/bash.)
  2. Failing that, from inside your server container attempt to reach the database host/port using netcat: nc -zv <db-host> <db-port> (e.g. nc -zv 192.168.12.34 5432). This should report 'open' if it's reachable.
  3. Failing that, check for firewall or network security settings that might prevent communication.

Clone this wiki locally