Docker Compose PostgreSQL Template

By default, data in a container is ephemeral and lost when the container is deleted. To persist your database data on your local machine, use the volumes tag to map a local directory to the container's data path /var/lib/postgresql/data/.

Use the ${PWD} variable to reference your current working directory.

services:
  database:
    # ...
    volumes:
      - ${PWD}/db-data/:/var/lib/postgresql/data/

To set up a PostgreSQL database using Docker Compose, create a docker-compose.yml file in your project root. This configuration uses the official PostgreSQL image and maps the default port 5432 to your host machine so you can connect to it from outside the container.

Key configuration parameters:

• image: Specifies the Postgres version (e.g., postgres:17).
• ports: Maps [host_port]:[container_port].
• environment: Sets POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB.

Note: The service name (e.g., database) is used as the hostname when connecting from other services within the same Docker network.

services:
  database:
    image: 'postgres:17'
    ports:
      - 5432:5432
    environment:
      POSTGRES_USER: username
      POSTGRES_PASSWORD: password
      POSTGRES_DB: default_database

Instead of hardcoding credentials in docker-compose.yml, you can use a .env file located at your project root.

1. Create a .env file with your variables:

POSTGRES_USER=username
POSTGRES_PASSWORD=password
POSTGRES_DB=default_database

2. Update your docker-compose.yml to use the env_file tag:

services:
  database:
    # ... other config
    env_file:
      - .env

You can then remove the environment: block from your docker-compose.yml file.

You can automatically execute SQL scripts when the database is first initialized by mounting an .sql file to the /docker-entrypoint-initdb.d/ directory inside the container via a volume.

services:
  database:
    # ...
    volumes:
      - ${PWD}/init.sql:/docker-entrypoint-initdb.d/init.sql

The setup uses a custom bridge network named postgres-network to allow communication between the database and pgadmin services.

networks: 
  postgres-network:
    driver: bridge

The pgadmin service provides a web-based management interface for PostgreSQL using the dpage/pgadmin4 image.

Key configurations:

• Ports: Maps host port 15433 to container port 80.
• Dependencies: Requires the database service to be running (depends_on: - database).
• Environment: Loads configuration from a .env file.
• Persistence & Permissions:
  • Session data is persisted in the host directory ${PWD}/pgadmin-data/.
  • Important: If startup fails with a permission error, you must set the host folder owner to 5050:5050 before starting.

pgadmin:
    image: dpage/pgadmin4
    ports:
      - 15433:80
    env_file:
      - .env
    depends_on:
      - database
    networks:
      - postgres-network
    volumes:
      - ${PWD}/pgadmin-data/:/var/lib/pgadmin/

The database service runs a PostgreSQL instance using the postgres:17 image.

Key configurations:

• Ports: Maps host port 15432 to container port 5432.
• Environment: Loads configuration from a .env file.
• Persistence:
  • Database files are persisted in the host directory ${PWD}/db-data/.
  • Initialization scripts can be run by mounting an init.sql file from the host to /docker-entrypoint-initdb.d/init.sql.
• Networking: Connects to the postgres-network.

database:
  image: 'postgres:17'
  ports:
    - 15432:5432
  env_file:
    - .env
  networks:
    - postgres-network
  volumes:
    - ${PWD}/db-data/:/var/lib/postgresql/data/
    - ${PWD}/init.sql:/docker-entrypoint-initdb.d/init.sql

Use the following commands to manage your Postgres environment:

• Start the environment: Run this in the directory containing docker-compose.yml to build and start the services.
• Stop the environment: Use this to shut down the containers and free up system resources. This does not delete your volumes (persisted data).

# Start the database
docker compose up

# Stop the database
docker compose down