services:
  # Service name for our PostgreSQL database
  db:
    # We use a specific version of PostgreSQL for stability.
    # The 'alpine' tag means it's a smaller image size.
    image: postgres:16-alpine

    # This ensures the database container restarts automatically if it crashes or the server reboots.
    restart: always

    # Environment variables are loaded from the .env file.
    # These are used by the PostgreSQL image to create the user and database on first run.
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}

    # Port mapping: <HOST_PORT>:<CONTAINER_PORT>
    # - We expose the internal container port 5432 (PostgreSQL's default)
    # - to our custom port ${DB_PORT} (5433 from our .env) on our local machine.
    ports:
      - '${DB_PORT}:5432'

    # Volumes are essential to persist data.
    # - We create a named volume 'postgres_data'.
    # - All database files inside the container (/var/lib/postgresql/data) are stored in this volume.
    # - This means your data is safe even if you remove the container with 'docker-compose down'.
    volumes:
      - postgres_data:/var/lib/postgresql/data

    # A healthcheck to ensure the database is ready to accept connections
    # before other services (if any) might try to connect.
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${DB_USER} -d ${DB_NAME}']
      interval: 10s
      timeout: 5s
      retries: 5

# Top-level volumes definition. This is where Docker manages the named volume.
volumes:
  postgres_data: