cachet-docker/DOCKER.md

# Running Cachet with Docker

## Quick Start

```bash
# Build the image
docker compose build

# Generate an application key
APP_KEY=$(openssl rand -base64 32)

# Start the stack
APP_KEY="base64:$APP_KEY" docker compose up -d

# Wait for services to be healthy (about 30-60 seconds)
docker compose ps

# Create your first admin user
docker exec -it cachet-app php artisan cachet:make:user
```

Access Cachet at http://localhost:8000

## Configuration

### Environment Variables

Create a `.env` file in the project root or pass variables directly:

| Variable | Default | Description |
|----------|---------|-------------|
| `APP_KEY` | (required) | Application encryption key |
| `APP_URL` | `http://localhost:8000` | Public URL of your instance |
| `APP_ENV` | `production` | Environment (`local`, `production`) |
| `APP_DEBUG` | `false` | Enable debug mode |
| `APP_TIMEZONE` | `UTC` | Application timezone |
| `APP_PORT` | `8000` | Host port to expose |
| `DB_CONNECTION` | `pgsql` | Database driver (`pgsql`, `mysql`, `sqlite`) |
| `DB_HOST` | `database` | Database hostname |
| `DB_PORT` | `5432` | Database port |
| `DB_DATABASE` | `cachet` | Database name |
| `DB_USERNAME` | `cachet` | Database username |
| `DB_PASSWORD` | `secret` | Database password |
| `REDIS_HOST` | `redis` | Redis hostname |
| `CACHE_STORE` | `redis` | Cache driver |
| `MAIL_MAILER` | `log` | Mail driver (`smtp`, `log`, `mailpit`) |
| `MAIL_HOST` | `mailpit` | SMTP host |
| `MAIL_PORT` | `1025` | SMTP port |
| `MAIL_FROM_ADDRESS` | `hello@example.com` | From email address |

### Generate Application Key

```bash
# Using OpenSSL
echo "base64:$(openssl rand -base64 32)"

# Or using PHP
docker run --rm php:8.2-cli php -r "echo 'base64:' . base64_encode(random_bytes(32)) . PHP_EOL;"
```

## Production Deployment

### Using docker-compose.yml

```bash
# Create environment file
cat > .env.docker << 'EOF'
APP_KEY=base64:your-generated-key-here
APP_URL=https://status.example.com
APP_ENV=production
APP_DEBUG=false
DB_PASSWORD=your-secure-password
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-smtp-user
MAIL_PASSWORD=your-smtp-password
MAIL_FROM_ADDRESS=status@example.com
EOF

# Start with custom env file
docker compose --env-file .env.docker up -d
```

### Using External Database

To use an external PostgreSQL or MySQL database:

```bash
docker compose up -d app redis  # Skip the database service

# Or modify docker-compose.yml to remove the database service
# and update DB_HOST to point to your external database
```

### Reverse Proxy (nginx/Traefik)

When running behind a reverse proxy, set:

```bash
APP_URL=https://status.example.com
CACHET_TRUSTED_PROXIES=*  # Or specific proxy IPs
```

## Development

### Using docker-compose.dev.yml

```bash
docker compose -f docker-compose.dev.yml up -d
```

Features:
- Source code mounted for hot-reload
- PostgreSQL exposed on port 5432
- Redis exposed on port 6379
- Mailpit UI at http://localhost:8025

### Running Commands

```bash
# Artisan commands
docker exec -it cachet-app php artisan <command>

# Composer
docker exec -it cachet-app composer <command>

# Database shell
docker exec -it cachet-db psql -U cachet -d cachet
```

## Maintenance

### View Logs

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

# Specific service
docker compose logs -f app

# Application logs inside container
docker exec -it cachet-app tail -f storage/logs/laravel.log
```

### Backup Database

```bash
# PostgreSQL
docker exec cachet-db pg_dump -U cachet cachet > backup.sql

# Restore
docker exec -i cachet-db psql -U cachet cachet < backup.sql
```

### Update Cachet

```bash
docker compose down
git pull
docker compose build --no-cache
docker compose up -d
docker exec -it cachet-app php artisan migrate --force
```

### Clear Caches

```bash
docker exec -it cachet-app php artisan cache:clear
docker exec -it cachet-app php artisan config:clear
docker exec -it cachet-app php artisan view:clear
```

## Troubleshooting

### Container Won't Start

Check logs:
```bash
docker compose logs app
```

Common issues:
- Missing `APP_KEY`: Generate one using the commands above
- Database not ready: Wait for health checks or increase `start_period`

### Permission Errors

```bash
docker exec -it cachet-app chown -R www-data:www-data storage bootstrap/cache
docker exec -it cachet-app chmod -R 775 storage bootstrap/cache
```

### Database Connection Failed

Verify database is healthy:
```bash
docker compose ps
docker exec cachet-db pg_isready -U cachet
```

### Queue Jobs Not Processing

Check queue worker:
```bash
docker exec -it cachet-app supervisorctl status queue-worker
docker exec -it cachet-app cat storage/logs/queue.log
```

Restart queue worker:
```bash
docker exec -it cachet-app supervisorctl restart queue-worker
```

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                        cachet-app                           │
│  ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  nginx  │  │ php-fpm │  │  queue   │  │   scheduler   │  │
│  │  :8000  │  │  :9000  │  │  worker  │  │ (every minute)│  │
│  └─────────┘  └─────────┘  └──────────┘  └───────────────┘  │
│                    supervised by supervisord                 │
└─────────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
    ┌────────────┐       ┌────────────┐       ┌────────────┐
    │  postgres  │       │   redis    │       │  mailpit   │
    │   :5432    │       │   :6379    │       │   :8025    │
    └────────────┘       └────────────┘       └────────────┘
```

## Building Custom Image

```bash
# Production image
docker build --target production -t cachet:latest .

# Development image
docker build --target development -t cachet:dev .

# With custom registry
docker build --target production -t registry.example.com/cachet:v3 .
docker push registry.example.com/cachet:v3
```