paper-dynasty-database/DOCKER_QUICKSTART.md

Docker Quick Start Guide

🚀 Starting PostgreSQL for Local Development

Option 1: Using Docker Compose (Recommended)

Start PostgreSQL + Adminer (database UI):

# Start the database
docker-compose up -d postgres adminer

# Or use podman-compose
podman-compose up -d postgres adminer

What this does:

• ✅ Starts PostgreSQL 17 on port 5432
• ✅ Starts Adminer (database UI) on port 8080
• ✅ Creates persistent volume for database data
• ✅ Sets up health checks

Access Adminer:

• Open browser: http://localhost:8080
• System: PostgreSQL
• Server: pd_postgres (or localhost if connecting from host)
• Username: pd_admin (from .env or default)
• Password: pd_dev_password (from .env or default)
• Database: pd_master (from .env or default)

---

Option 2: Native Docker/Podman Commands

Start PostgreSQL container:

# Using docker
docker run -d \
  --name pd_postgres \
  -e POSTGRES_DB=pd_master \
  -e POSTGRES_USER=pd_admin \
  -e POSTGRES_PASSWORD=pd_dev_password \
  -p 5432:5432 \
  -v pd_postgres_data:/var/lib/postgresql/data \
  postgres:17-alpine

# Using podman
podman run -d \
  --name pd_postgres \
  -e POSTGRES_DB=pd_master \
  -e POSTGRES_USER=pd_admin \
  -e POSTGRES_PASSWORD=pd_dev_password \
  -p 5432:5432 \
  -v pd_postgres_data:/var/lib/postgresql/data \
  postgres:17-alpine

---

📝 Common Commands

Start Services

# Start all services
docker-compose up -d

# Start specific services
docker-compose up -d postgres adminer

# Start and view logs
docker-compose up postgres adminer

Stop Services

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ deletes database data)
docker-compose down -v

View Logs

# View all logs
docker-compose logs -f

# View PostgreSQL logs only
docker-compose logs -f postgres

# View last 50 lines
docker-compose logs --tail=50 postgres

Check Status

# List running containers
docker-compose ps

# Or with native docker/podman
docker ps -a
podman ps -a

Database Backup

# Backup database
docker exec pd_postgres pg_dump -U pd_admin pd_master > backup_$(date +%Y%m%d).sql

# Or with podman
podman exec pd_postgres pg_dump -U pd_admin pd_master > backup_$(date +%Y%m%d).sql

Database Restore

# Restore from backup
docker exec -i pd_postgres psql -U pd_admin pd_master < backup_20251107.sql

# Or with podman
podman exec -i pd_postgres psql -U pd_admin pd_master < backup_20251107.sql

---

🔧 Configuration

Environment Variables

Create a .env file (or use .env.example as a template):

# Database Configuration
POSTGRES_DB=pd_master
POSTGRES_USER=pd_admin
POSTGRES_PASSWORD=pd_dev_password
POSTGRES_PORT=5432

# Application Configuration
LOG_LEVEL=INFO
API_TOKEN=dev_token_here
TZ=America/New_York

Docker Compose will automatically load these variables.

---

🧪 Testing Database Connection

From Host Machine

Using psql (if installed):

psql -h localhost -U pd_admin -d pd_master
# Enter password when prompted

Using Python:

# Set environment variables first
export DATABASE_TYPE=postgresql
export POSTGRES_HOST=localhost
export POSTGRES_DB=pd_master
export POSTGRES_USER=pd_admin
export POSTGRES_PASSWORD=pd_dev_password

# Test connection
python -c "from app.db_engine import db; db.connect(); print('✓ Connected'); db.close()"

From Inside Container

# Connect to PostgreSQL container
docker exec -it pd_postgres psql -U pd_admin -d pd_master

# Or with podman
podman exec -it pd_postgres psql -U pd_admin -d pd_master

# Common psql commands:
# \dt          - List tables
# \d table     - Describe table
# \l           - List databases
# \du          - List users
# \q           - Quit

---

🏃 Running the Application

Option 1: Local Python (Recommended for Development)

# Ensure PostgreSQL is running in Docker
docker-compose up -d postgres

# Set environment variables
export DATABASE_TYPE=postgresql
export POSTGRES_HOST=localhost
export POSTGRES_DB=pd_master
export POSTGRES_USER=pd_admin
export POSTGRES_PASSWORD=pd_dev_password

# Install dependencies
pip install -r requirements.txt

# Run with hot reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Benefits:

• ✅ Fast hot-reload during development
• ✅ Easy debugging
• ✅ Direct access to logs
• ✅ Can use SQLite or PostgreSQL easily

Option 2: Docker Compose (Full Stack)

# Uncomment the 'api' service in docker-compose.yml first

# Build and start everything
docker-compose up --build

# Or run in background
docker-compose up -d

Benefits:

• ✅ Production-like environment
• ✅ Isolated from host system
• ✅ Easy to share with team

---

🛠️ Troubleshooting

Port Already in Use

Error: bind: address already in use

Solution:

# Check what's using port 5432
sudo lsof -i :5432
# or
sudo netstat -tulpn | grep 5432

# Stop conflicting service
sudo systemctl stop postgresql  # If system PostgreSQL is running

# Change port in docker-compose.yml
ports:
  - "5433:5432"  # Use 5433 on host instead

Can't Connect to Database

Check container is running:

docker-compose ps
docker logs pd_postgres

Check PostgreSQL is ready:

docker exec pd_postgres pg_isready -U pd_admin

Verify credentials:

# Check environment variables
docker exec pd_postgres env | grep POSTGRES

Database Data Corruption

Reset database (⚠️ deletes all data):

# Stop containers
docker-compose down

# Remove volumes
docker volume rm database_postgres_data
# or
docker-compose down -v

# Restart
docker-compose up -d

Permission Errors

Fix volume permissions:

# Docker
sudo chown -R $(whoami):$(whoami) ./storage ./logs

# Podman (rootless)
# Usually no issues with rootless podman

---

📊 Performance Tuning

PostgreSQL Configuration

Edit docker-compose.yml to add PostgreSQL tuning:

postgres:
  # ... other settings ...
  command: >
    postgres
    -c shared_buffers=256MB
    -c max_connections=100
    -c effective_cache_size=1GB
    -c maintenance_work_mem=64MB
    -c checkpoint_completion_target=0.9    

---

🔐 Production Considerations

DO NOT Use in Production As-Is

This docker-compose.yml is for local development only. For production:

1. ✅ Use strong passwords
2. ✅ Don't expose ports publicly
3. ✅ Set up proper backups
4. ✅ Use Docker secrets instead of environment variables
5. ✅ Set up SSL/TLS for PostgreSQL connections
6. ✅ Configure proper resource limits
7. ✅ Use separate PostgreSQL server (not container)

---

📚 Additional Resources

• PostgreSQL Docs: https://www.postgresql.org/docs/
• Docker Compose Docs: https://docs.docker.com/compose/
• Adminer Docs: https://www.adminer.org/
• Migration Guide: See POSTGRES_MIGRATION_PLAN.md
• Environment Config: See .env.example

---

Last Updated: 2025-11-07 For Help: See POSTGRES_MIGRATION_PLAN.md or MIGRATION_PROGRESS.md