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):**
```bash
# 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:**
```bash
# 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
```bash
# 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
```bash
# Stop all services
docker-compose down

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

### View Logs
```bash
# 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
```bash
# List running containers
docker-compose ps

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

### Database Backup
```bash
# 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
```bash
# 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):

```bash
# 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):**
```bash
psql -h localhost -U pd_admin -d pd_master
# Enter password when prompted
```

**Using Python:**
```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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:**
```bash
# 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:**
```bash
docker-compose ps
docker logs pd_postgres
```

**Check PostgreSQL is ready:**
```bash
docker exec pd_postgres pg_isready -U pd_admin
```

**Verify credentials:**
```bash
# Check environment variables
docker exec pd_postgres env | grep POSTGRES
```

### Database Data Corruption

**Reset database (⚠️ deletes all data):**
```bash
# 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:**
```bash
# 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:

```yaml
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`