michaelschiemer/deployment/stacks/postgresql-production/README.md

PostgreSQL Production Stack - Production Database

Overview

Production-ready PostgreSQL 16 database stack with automated backup system and performance optimization.

Features:

• PostgreSQL 16 Alpine (lightweight, secure)
• Automated daily backups with configurable retention
• Performance-optimized configuration (2GB memory allocation)
• Health checks and automatic recovery
• Persistent storage with named volumes
• Isolated postgres-production-internal network
• Resource limits for stability

Services

• postgres-production - PostgreSQL 16 database server
• postgres-production-backup - Automated backup service with cron scheduling

Prerequisites

1. Docker and Docker Compose installed
2. Environment file created (.env)

Configuration

1. Create Environment File

cp .env.example .env

2. Generate Secure Password

openssl rand -base64 32

Update .env:

POSTGRES_DB=michaelschiemer
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<generated-password>
BACKUP_RETENTION_DAYS=7
BACKUP_SCHEDULE=0 2 * * *

Deployment

Initial Setup

# Create environment file
cp .env.example .env

# Generate and set password
openssl rand -base64 32
# Update POSTGRES_PASSWORD in .env

# Start services
docker compose up -d

# Check logs
docker compose logs -f

# Verify health
docker compose ps

Verify Deployment

# Check PostgreSQL is running
docker exec postgres-production pg_isready -U postgres -d michaelschiemer

# Expected: postgres-production:5432 - accepting connections

# Check backup service
docker compose logs postgres-production-backup

# Expected: Initial backup completed successfully

Integration with Production Application Stack

The Production Application Stack connects to this database via the postgres-production-internal network.

Connection Configuration in deployment/stacks/production/.env:

DB_HOST=postgres-production
DB_PORT=5432
DB_DATABASE=michaelschiemer
DB_USERNAME=postgres
DB_PASSWORD=<same-as-postgres-production-password>

Network Connection: The Production Application Stack must be connected to the postgres-production-internal network.

Usage

Database Access

From Host Machine

# Connect to database
docker exec -it postgres-production psql -U postgres -d michaelschiemer

# Run SQL query
docker exec postgres-production psql -U postgres -d michaelschiemer -c "SELECT version();"

From Application Container

# Connection string format
postgresql://postgres:password@postgres-production:5432/michaelschiemer

Backup Management

Manual Backup

# Trigger manual backup
docker exec postgres-production-backup /scripts/backup.sh

# List backups
ls -lh backups/

# Example output:
# postgres_michaelschiemer_20250130_020000.sql.gz

Restore from Backup

# List available backups
docker exec postgres-production-backup ls -lh /backups

# Restore specific backup
docker exec -it postgres-production-backup /scripts/restore.sh /backups/postgres_michaelschiemer_20250130_020000.sql.gz

# ⚠️ WARNING: This will DROP and RECREATE the database!

Network Isolation

This stack uses its own isolated network:

• Network: postgres-production-internal
• Purpose: Isolate Production database from other services
• Access: Only services explicitly connected to this network can access the database

Connecting Application Stack:

# In deployment/stacks/production/docker-compose.production.yml
networks:
  postgres-production-internal:
    external: true
    name: postgres-production-internal

Security

Network Isolation

• PostgreSQL only accessible via postgres-production-internal network
• No external ports exposed
• Service-to-service communication only

Authentication

• Strong password required (generated with openssl rand -base64 32)
• No default passwords
• Password stored in environment variables only

Monitoring

Health Checks

# Check service health
docker compose ps

# Expected: Both services "healthy"

# Manual health check
docker exec postgres-production pg_isready -U postgres -d michaelschiemer

Resource Usage

# Database container stats
docker stats postgres-production --no-stream

# Disk usage
docker exec postgres-production du -sh /var/lib/postgresql/data

Logs

# PostgreSQL logs
docker compose logs postgres-production

# Backup logs
docker compose logs postgres-production-backup

# Real-time monitoring
docker compose logs -f

Troubleshooting

Database Won't Start

# Check logs
docker compose logs postgres-production

# Common issues:
# 1. Invalid configuration
docker exec postgres-production postgres --check

# 2. Permission issues
docker exec postgres-production ls -la /var/lib/postgresql/data

Connection Refused from Application

# 1. Check PostgreSQL is running
docker compose ps postgres-production

# 2. Verify network
docker network inspect postgres-production-internal | grep postgres-production

# 3. Check if application is connected to network
docker network inspect postgres-production-internal | grep app

Differences from Staging Stack

Aspect	Production	Staging
Container Name	postgres-production	postgres-staging
Network	postgres-production-internal	postgres-staging-internal
Volume	postgres-production-data	postgres-staging-data
Database	michaelschiemer	michaelschiemer_staging
Backup Retention	7 days (configurable)	7 days (configurable)

Additional Resources

• PostgreSQL Documentation: https://www.postgresql.org/docs/16/
• Performance Tuning: https://wiki.postgresql.org/wiki/Performance_Optimization
• Backup Best Practices: https://www.postgresql.org/docs/16/backup.html