Epicure/DOCKER_DEPLOYMENT.md

Docker Deployment Guide

This guide explains how to deploy the Epicure application using Docker and Docker Compose.

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• At least 2GB RAM available
• A domain name (for production)

Quick Start - Development

For local development, use the existing compose setup:

docker compose -f docker/compose.yml up -d
pnpm install
pnpm db:migrate
pnpm db:seed
pnpm dev

Access the app at http://localhost:3000 MinIO console: http://localhost:9001 (minioadmin / minioadmin)

Production Deployment

1. Prepare Environment

Copy and configure the production environment file:

cp docker/.env.production .env.production

Edit .env.production and set:

• POSTGRES_PASSWORD - Strong random password
• REDIS_PASSWORD - Strong random password
• MINIO_ROOT_PASSWORD - Strong random password
• BETTER_AUTH_SECRET - Generate: openssl rand -base64 32
• BETTER_AUTH_URL - Your domain (e.g., https://example.com)
• DOMAIN - Your domain name
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET - OAuth credentials
• OPENROUTER_API_KEY - AI provider key
• SMTP_* - Email configuration

2. Build Docker Image

docker build -f Dockerfile -t epicure-web:latest .

Or let Docker Compose build it automatically.

3. Deploy with Docker Compose

docker compose -f docker/docker-compose.deploy.yml --env-file .env.production up -d

4. Verify Deployment

# Check all services are running
docker compose -f docker/docker-compose.deploy.yml ps

# Check application logs
docker compose -f docker/docker-compose.deploy.yml logs -f web

# Verify database migration ran
docker compose -f docker/docker-compose.deploy.yml logs web | grep -i migration

5. Access the Application

• Main app: https://your-domain.com
• MinIO console (if exposed): https://minio.your-domain.com

Production Configuration

Caddy Configuration

Edit docker/Caddyfile.prod to customize:

• SSL/TLS settings
• Security headers
• Compression
• Rate limiting

Database Backups

To backup PostgreSQL:

docker compose -f docker/docker-compose.deploy.yml exec postgres pg_dump -U epicure epicure > backup.sql

To restore:

docker compose -f docker/docker-compose.deploy.yml exec -T postgres psql -U epicure epicure < backup.sql

MinIO Backups

MinIO data is stored in the minio_data volume. Backup the volume:

docker run --rm -v epicure_minio_data:/data -v $(pwd):/backup alpine tar czf /backup/minio-backup.tar.gz -C /data .

Maintenance

View Logs

# All services
docker compose -f docker/docker-compose.deploy.yml logs -f

# Specific service
docker compose -f docker/docker-compose.deploy.yml logs -f web
docker compose -f docker/docker-compose.deploy.yml logs -f postgres

Database Migrations

To run additional migrations:

docker compose -f docker/docker-compose.deploy.yml exec web pnpm db:migrate

Update Application

1. Build new image:

docker build -f Dockerfile -t epicure-web:latest .

2. Restart service:

docker compose -f docker/docker-compose.deploy.yml up -d web

Clean Up

Remove all containers and volumes:

docker compose -f docker/docker-compose.deploy.yml down -v

Security Considerations

1. Passwords: Use strong, random passwords (minimum 32 characters)
2. Environment Variables: Never commit .env.production to git
3. TLS/SSL: Caddy automatically handles Let's Encrypt certificates
4. Firewall: Only expose ports 80 and 443 in production
5. Updates: Regularly update Docker images:

   docker compose -f docker/docker-compose.deploy.yml pull
   docker compose -f docker/docker-compose.deploy.yml up -d
   

6. MinIO: Change default credentials and optionally disable console in production

Troubleshooting

Application won't start

Check logs:

docker compose -f docker/docker-compose.deploy.yml logs web

Common issues:

• Database connection: Ensure POSTGRES_PASSWORD matches
• Redis connection: Verify REDIS_PASSWORD is set
• Storage connection: Check MinIO credentials and bucket exists

Database migration failed

# Check database status
docker compose -f docker/docker-compose.deploy.yml exec postgres psql -U epicure -d epicure -c "\d"

# Run migrations manually
docker compose -f docker/docker-compose.deploy.yml exec web pnpm db:migrate

MinIO initialization failed

# Check MinIO logs
docker compose -f docker/docker-compose.deploy.yml logs minio

# Reinitialize bucket
docker compose -f docker/docker-compose.deploy.yml restart minio-init

Performance issues

• Increase RAM: Edit docker-compose.deploy.yml and add mem_limit
• Check logs for slow queries
• Scale PostgreSQL: Consider managed database service for production

Advanced: Kubernetes Deployment

For Kubernetes, convert this Docker Compose stack:

kompose convert -f docker/docker-compose.deploy.yml -o k8s/

This generates Kubernetes manifests ready for deployment to EKS, AKS, or GKE.

Support

For issues or questions, check:

• Application logs: docker compose logs
• Service health: docker compose ps
• Database status: docker compose exec postgres pg_isready