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

Production Deployment

1. Prepare Environment

Copy and configure the production environment file:

cp docker/.env.production .env.production

Or for Portainer deployment, copy the stack environment file:

cp docker/stack.env stack.env.local

Edit the file 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
• NEXT_PUBLIC_VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY - Push notification keys

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

Portainer Deployment

Portainer provides a web UI for managing Docker containers and deploying stacks easily.

Portainer Setup

1. Prepare Environment File

   Copy the stack environment template:

   cp docker/stack.env stack.env.local
   

   Edit stack.env.local with your production values.

2. Access Portainer

   Open your Portainer instance (typically https://portainer.your-domain.com).

3. Deploy Stack

   • Go to Stacks → Add Stack
   • Choose Docker Compose mode
   • Select Upload to upload the compose file, or use Editor to paste the contents of docker/docker-compose.deploy.yml
   • Copy the contents of docker/stack.env into the Environment variables section
   • Click Deploy the stack

   Alternative: Using Environment File UI

   • In the stack creation form, there's an "Environment file" option
   • You can paste the entire stack.env content there
   • Portainer will parse and use all variables

4. Verify Deployment

   • Check the Containers tab to see all services running
   • View logs by clicking on each container
   • Verify the app is accessible at https://your-domain.com

Portainer Stack Update

To update the application after code changes:

1. Build new Docker image locally:

   docker build -f Dockerfile -t epicure-web:latest .
   docker push your-registry/epicure-web:latest
   

2. In Portainer:

   • Go to your stack
   • Click Editor
   • Update the image reference if needed
   • Click Update the stack

Portainer Secrets (Optional)

For better security, use Portainer Secrets instead of environment variables:

1. Create a secret in Portainer with sensitive values
2. Reference it in the compose file: ${POSTGRES_PASSWORD}
3. Portainer will inject the secret value during 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