euchre_camp/docs/deployment/DOCKER.md

Docker Deployment Guide

This guide covers how to run EuchreCamp using Docker and Docker Compose.

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2.0+
• Make (optional, for using Makefile commands)

Quick Start

1. Environment Setup

Create a .env file in the project root:

cp .env.example .env

Update the .env file with your configuration:

# Database Configuration (PostgreSQL in Docker)
DATABASE_PROVIDER=postgresql
DATABASE_URL=postgresql://euchre:euchrepassword@postgres:5432/euchre_camp
DATABASE_SHADOW_URL=postgresql://euchre:euchrepassword@postgres:5432/euchre_camp_shadow

# Better Auth (generate a secure secret for production)
BETTER_AUTH_SECRET=your-secret-key-change-in-production
BETTER_AUTH_URL=http://localhost:3000

# Application
NODE_ENV=production
TRUSTED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

2. Build and Run

Production Mode

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

Development Mode

# Use development override configuration
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

# Or use the shorthand
docker-compose --profile dev up -d

3. Access the Application

• Web Application: http://localhost:3000
• PostgreSQL: localhost:5432 (default) or 5433 in development

Service Architecture

┌─────────────────────────────────────────────┐
│                 EuchreCamp                  │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐    ┌──────────────────┐  │
│  │   Next.js    │◄───│   PostgreSQL     │  │
│  │   App        │    │   Database       │  │
│  │              │    │                  │  │
│  │  Port: 3000  │    │  Port: 5432      │  │
│  └──────────────┘    └──────────────────┘  │
│                                             │
└─────────────────────────────────────────────┘

Service Details

App Service

• Image: Multi-stage Next.js build
• Port: 3000
• Environment: Production or Development
• Volumes:
  • app_data: Persistent storage for uploads

PostgreSQL Service

• Image: postgres:15-alpine
• Port: 5432 (production) / 5433 (development)
• Data Volume: postgres_data (persistent)
• Health Check: Uses pg_isready

Database Management

View Database Data

# Access PostgreSQL shell
docker exec -it euchre-camp-postgres psql -U euchre -d euchre_camp

# List tables
\dt

# Exit
\q

Backup Database

# Create backup
docker exec euchre-camp-postgres pg_dump -U euchre euchre_camp > backup.sql

# Restore backup
docker exec -i euchre-camp-postgres psql -U euchre euchre_camp < backup.sql

Reset Database

# Remove all data and restart
docker-compose down -v
docker-compose up -d

Running Commands

Run Database Migrations

# Apply migrations
docker-compose exec app npx prisma migrate deploy

# Generate Prisma client
docker-compose exec app npx prisma generate

# Open Prisma Studio
docker-compose exec app npx prisma studio

Create Admin User

# Create admin user via script
docker-compose exec app node scripts/create-admin-via-api.js

Seed Database

# Run seed script
docker-compose exec app node scripts/seed.js

Development Workflow

Hot Reloading

Development mode supports hot reloading:

# Start in development mode
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d

# View logs
docker-compose logs -f app

Modifying Code

Changes to source code are automatically reflected due to volume mounting:

# Edit a file locally
nano src/app/page.tsx

# Next.js will automatically reload

Troubleshooting

Common Issues

1. Database Connection Failed

# Check if PostgreSQL is running
docker ps | grep postgres

# Check logs
docker logs euchre-camp-postgres

# Restart services
docker-compose restart postgres

2. Port Already in Use

# Check what's using port 3000
lsof -i :3000

# Change port in docker-compose.yml
# ports:
#   - "3001:3000"

3. Permission Denied

# Ensure scripts are executable
chmod +x scripts/*.sh

# Check volume permissions
docker exec euchre-camp-app ls -la /app

4. Migration Errors

# Reset database
docker-compose down -v
docker-compose up -d

# Apply migrations manually
docker-compose exec app npx prisma migrate deploy

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f app
docker-compose logs -f postgres

Container Shell Access

# App container
docker exec -it euchre-camp-app sh

# PostgreSQL container
docker exec -it euchre-camp-postgres sh

Production Deployment

Environment Variables

For production, ensure you set secure values:

# Generate a secure secret
BETTER_AUTH_SECRET=$(openssl rand -base64 32)

# Use real domain
BETTER_AUTH_URL=https://euchrecamp.example.com

# Trusted origins
TRUSTED_ORIGINS=https://euchrecamp.example.com,https://www.euchrecamp.example.com

Security Considerations

1. Change default PostgreSQL password:

   POSTGRES_PASSWORD=your-secure-password
   

2. Use SSL/TLS for database connections:

   DATABASE_URL=postgresql://euchre:password@postgres:5432/euchre_camp?sslmode=require
   

3. Restrict network access:

   • Don't expose PostgreSQL port to public internet
   • Use firewall rules to restrict access

4. Regular backups:

   • Schedule automated database backups
   • Test restoration process

Docker Swarm / Kubernetes

For production orchestration, consider:

1. Separate database service - Use managed PostgreSQL (RDS, Cloud SQL)
2. Secrets management - Use Docker secrets or Kubernetes Secrets
3. Health checks - Configure proper health checks
4. Resource limits - Set CPU and memory limits
5. Replicas - Run multiple app instances for high availability

Makefile (Optional)

Create a Makefile for convenient commands:

.PHONY: up down logs build shell-migrate

up:
	docker-compose up -d

down:
	docker-compose down

logs:
	docker-compose logs -f

build:
	docker-compose build --no-cache

shell-app:
	docker exec -it euchre-camp-app sh

shell-db:
	docker exec -it euchre-camp-postgres psql -U euchre -d euchre_camp

migrate:
	docker-compose exec app npx prisma migrate deploy

seed:
	docker-compose exec app node scripts/seed.js

Performance Tuning

PostgreSQL Configuration

Edit docker-compose.yml to tune PostgreSQL:

postgres:
  # ... other config ...
  command: >
    postgres
    -c max_connections=200
    -c shared_buffers=256MB
    -c effective_cache_size=1GB
    -c maintenance_work_mem=64MB
    -c checkpoint_completion_target=0.9
    -c wal_buffers=16MB
    -c default_statistics_target=100

Next.js Optimization

The Dockerfile uses multi-stage build for optimal size and performance:

• Builder stage: Installs all dependencies and builds the app
• Runner stage: Copies only the built artifacts and production dependencies

References

• Docker Compose Documentation
• PostgreSQL Docker Image
• Next.js Deployment
• Prisma Deployment