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

PostgreSQL

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

Appdata Location

Create appdata/postgres and appdata/pgadmin in the project root, not inside docker-compose-files/.

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. Create appdata and render the template:

   mkdir -p appdata/postgres/{data,backups} appdata/pgadmin
   ./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 pgAdmin cannot write its data directory, correct ownership for its container user before restarting it.

Useful Commands

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

Backup

Back up appdata/postgres and appdata/pgadmin. Store database dumps in appdata/postgres/backups.