michaelschiemer/deployment/stacks/postgresql-staging

PostgreSQL Staging Stack - Staging Database

Overview

Staging PostgreSQL 16 database stack with automated backup system for testing and development.

Features:

• PostgreSQL 16 Alpine (lightweight, secure)
• Automated daily backups with shorter retention (3 days)
• Performance-optimized configuration (1GB memory allocation)
• Health checks and automatic recovery
• Persistent storage with named volumes
• Isolated postgres-staging-internal network
• Resource limits optimized for staging workloads

Services

• postgres-staging - PostgreSQL 16 database server
• postgres-staging-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_staging
POSTGRES_USER=postgres
POSTGRES_PASSWORD=<generated-password>
BACKUP_RETENTION_DAYS=3
BACKUP_SCHEDULE=0 3 * * *

Note: Staging uses shorter backup retention (3 days) and runs backups at 3 AM (1 hour after production) to reduce resource contention.

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-staging pg_isready -U postgres -d michaelschiemer_staging

# Expected: postgres-staging:5432 - accepting connections

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

# Expected: Initial backup completed successfully

Integration with Staging Application Stack

The Staging Application Stack connects to this database via the postgres-staging-internal network.

Connection Configuration in docker-compose.staging.yml:

DB_HOST=postgres-staging
DB_PORT=5432
DB_DATABASE=michaelschiemer_staging
DB_USERNAME=postgres
DB_PASSWORD=<same-as-postgres-staging-password>

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

Usage

Database Access

From Host Machine

# Connect to database
docker exec -it postgres-staging psql -U postgres -d michaelschiemer_staging

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

From Application Container

# Connection string format
postgresql://postgres:password@postgres-staging:5432/michaelschiemer_staging

Backup Management

Manual Backup

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

# List backups
ls -lh backups/

# Example output:
# postgres_michaelschiemer_staging_20250130_030000.sql.gz

Restore from Backup

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

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

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

Network Isolation

This stack uses its own isolated network:

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

Connecting Application Stack:

# In docker-compose.staging.yml
networks:
  postgres-staging-internal:
    external: true
    name: postgres-staging-internal

Security

Network Isolation

• PostgreSQL only accessible via postgres-staging-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

Note: Staging passwords can be different from Production, but should still be secure.

Monitoring

Health Checks

# Check service health
docker compose ps

# Expected: Both services "healthy"

# Manual health check
docker exec postgres-staging pg_isready -U postgres -d michaelschiemer_staging

Resource Usage

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

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

Logs

# PostgreSQL logs
docker compose logs postgres-staging

# Backup logs
docker compose logs postgres-staging-backup

# Real-time monitoring
docker compose logs -f

Troubleshooting

Database Won't Start

# Check logs
docker compose logs postgres-staging

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

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

Connection Refused from Application

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

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

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

Differences from Production 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
Memory Limit	2GB	1GB
Backup Retention	7 days	3 days
Backup Schedule	2 AM	3 AM

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