cachet-docker/DOCKER.md

Running Cachet with Docker

Quick Start

# 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

# 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

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

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:

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

Development

Using docker-compose.dev.yml

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

# 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

# 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

# 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

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

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:

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

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:

docker compose ps
docker exec cachet-db pg_isready -U cachet

Queue Jobs Not Processing

Check queue worker:

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

Restart queue worker:

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

# 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