chore(docker): add docker support
This commit is contained in:
247
DOCKER.md
Normal file
247
DOCKER.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user