homelab-blueprint/docker-compose-files/postgres/README.md

PostgreSQL

Docker deployment for PostgreSQL and pgAdmin. Run all commands from the repository root.

Persistent Data

PostgreSQL data, database dumps, and pgAdmin state are stored in the Docker-managed named volumes postgres_data, postgres_backups, and pgadmin_data.

Existing bind-mount deployments must migrate their database and pgAdmin data before recreating the stack. Do not start PostgreSQL against an empty named volume and assume the previous database was imported.

Installation

1. Create .env if it does not exist:

   cp -n .env.sample .env
   

2. Set the required values in .env:

   TZ=Africa/Johannesburg
   POSTGRES_USER=postgres
   POSTGRES_PASSWORD=<strong-password>
   POSTGRES_DB=maindb
   PGADMIN_EMAIL=admin@example.com
   PGADMIN_PASSWORD=<strong-password>
   DOCKERLOGGING_MAXFILE=3
   DOCKERLOGGING_MAXSIZE=10m
   

3. Render the template:

   ./substitute_env.sh docker-compose-files/postgres/template.yaml docker-compose.postgres.yml .env
   

4. Validate and start the stack:

   docker compose -f docker-compose.postgres.yml config --quiet
   docker compose -f docker-compose.postgres.yml up -d
   

5. Verify the containers and open pgAdmin at http://<HOST_IP>:8484:

   docker compose -f docker-compose.postgres.yml ps
   docker compose -f docker-compose.postgres.yml logs --tail=100
   

Apply Configuration Changes

./substitute_env.sh docker-compose-files/postgres/template.yaml docker-compose.postgres.yml .env
docker compose -f docker-compose.postgres.yml up -d

Initial Setup

Add PostgreSQL to pgAdmin using host postgres, port 5432, and the database credentials from .env.

Network Requirements

• PostgreSQL is published on host port 5433.
• pgAdmin is published on host port 8484.
• Restrict both ports to trusted networks.

Troubleshooting

If an older generated Compose file reports write-permission errors, re-render it from the current template and recreate the stack. The current template uses named volumes instead of host-created appdata directories.

Useful Commands

docker compose -f docker-compose.postgres.yml exec postgres pg_isready

Backup

Back up all three named volumes and create regular logical database dumps with pg_dump.