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:

```bash
cp .env.example .env
```

Update the `.env` file with your configuration:

```env
# 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

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

# View logs
docker-compose logs -f

# Stop all services
docker-compose down
```

#### Development Mode

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

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

# List tables
\dt

# Exit
\q
```

### Backup Database

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

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

## Running Commands

### Run Database Migrations

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

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

### Seed Database

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

## Development Workflow

### Hot Reloading

Development mode supports hot reloading:

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

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

# Next.js will automatically reload
```

## Troubleshooting

### Common Issues

**1. Database Connection Failed**

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

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

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

**3. Permission Denied**

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

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

**4. Migration Errors**

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

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

### View Logs

```bash
# All services
docker-compose logs -f

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

### Container Shell Access

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

```env
# 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**:
   ```env
   POSTGRES_PASSWORD=your-secure-password
   ```

2. **Use SSL/TLS for database connections**:
   ```env
   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:

```makefile
.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:

```yaml
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](https://docs.docker.com/compose/)
- [PostgreSQL Docker Image](https://hub.docker.com/_/postgres)
- [Next.js Deployment](https://nextjs.org/docs/deployment)
- [Prisma Deployment](https://www.prisma.io/docs/concepts/components/prisma-migrate/deployment)