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:

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

```bash
cp docker/.env.production .env.production
```

Or for Portainer deployment, copy the stack environment file:

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

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

Or let Docker Compose build it automatically.

### 3. Deploy with Docker Compose

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

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

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

To restore:

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

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

## Maintenance

### View Logs

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

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

### Update Application

1. Build new image:
```bash
docker build -f Dockerfile -t epicure-web:latest .
```

2. Restart service:
```bash
docker compose -f docker/docker-compose.deploy.yml up -d web
```

### Clean Up

Remove all containers and volumes:

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

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

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

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