Add Docker Support for Easy Installation and Deployment

[PolNavarro]

Add Docker Support for Easy Installation and Deployment

Summary

This pull request adds comprehensive Docker support to Cachet v3, making installation and deployment significantly easier for users. The Docker setup includes a complete production-ready environment with Nginx, PHP-FPM, MySQL, and Redis.

What's Included

Core Docker Files

• Dockerfile - Production-ready multi-stage build with PHP 8.3, Nginx, and all required extensions
• docker-compose.yml - Complete orchestration with app, database, and Redis services
• .env.docker.example - Template environment file for Docker deployment
• DOCKER.md - Comprehensive documentation and setup instructions

Docker Configuration

• docker/nginx/nginx.conf - Optimized Nginx configuration for Laravel/Filament
• docker/php/cachet.ini - PHP optimizations for production
• docker/supervisor/supervisord.conf - Process management for Nginx, PHP-FPM, and queue workers
• docker/entrypoint.sh - Startup script with database migrations and caching

Why Docker Support?

1. Simplified Installation - One command deployment instead of complex manual setup
2. Consistent Environment - Same setup works across development, staging, and production
3. Dependency Management - All required services (MySQL, Redis) included and configured
4. Production Ready - Optimized for performance with proper security practices
5. Easy Scaling - Ready for container orchestration and load balancing

Features

Security Best Practices

• Internal network communication (MySQL/Redis not publicly exposed)
• Proper file permissions and user management
• Secure environment variable handling
• Production-optimized PHP and Nginx configurations

Production Optimizations

• Multi-stage Docker build for smaller images
• Composer optimizations and dependency caching
• PHP OPcache enabled
• Nginx static file serving optimizations
• Health checks for all services

Easy Setup

# Clone and setup
git clone https://github.com/cachethq/cachet.git
cd cachet

# Configure environment
cp .env.docker.example .env
# Edit .env with your passwords and domain

# Deploy with one command
docker-compose up -d --build

# Generate application key
docker-compose exec app php artisan key:generate

Architecture

The Docker setup uses a 3-service architecture:

1. app - Cachet application (Nginx + PHP-FPM)
2. db - MySQL 8.0 database
3. redis - Redis 7 for caching and sessions

All services communicate via a private Docker network with health checks ensuring proper startup order.

Benefits for Users

• Quick Start: Get Cachet running in minutes instead of hours
• Consistent Setup: Eliminates "works on my machine" issues
• Easy Updates: Simple container rebuilds for new versions
• Development Friendly: Perfect for testing and development environments
• Production Ready: Scales from single server to orchestrated deployments

Testing

The Docker setup has been thoroughly tested and includes:

• ✅ Successful database migrations
• ✅ Redis connectivity with Predis client
• ✅ Nginx + PHP-FPM communication
• ✅ Filament admin panel accessibility
• ✅ Static asset serving
• ✅ Environment variable configuration
• ✅ Health checks and dependency management

Documentation

Complete setup instructions are provided in DOCKER.md covering:

• Quick start guide
• Environment configuration
• Production deployment
• Troubleshooting
• Security considerations
• Scaling instructions

Future Enhancements

This Docker foundation enables:

• Kubernetes deployment manifests
• Docker Hub automated builds
• CI/CD integration
• Multi-stage environments (dev/staging/prod)
• Container monitoring and logging

Conclusion

This Docker implementation makes Cachet more accessible to users by eliminating complex setup procedures. It provides a production-ready foundation that can grow from simple single-server deployments to complex orchestrated environments.

We believe this addition will significantly improve the user experience and adoption of Cachet v3.

---

Files Changed:

• Added: Dockerfile
• Added: docker-compose.yml
• Added: .env.docker.example
• Added: DOCKER.md
• Added: docker/nginx/nginx.conf
• Added: docker/php/cachet.ini
• Added: docker/supervisor/supervisord.conf
• Added: docker/entrypoint.sh

[jbrooksuk]

@egelhaus this is great, thank you! Cachet 2.x previously had all Docker stuff located in the cachethq/docker repository. Do you think it makes sense to continue locating all of this there?

[PolNavarro]

Good, it can be done both ways. I personally prefer to have it all together in the same repo.

Basically, you can pass test with docker, basing commits or pull requests with github actions, from any branch. You know if it works or not. Also for me the most important thing, if you want them to use your software, the easier the better.

[egelhaus]

Hey @jbrooksuk ,
I didn't made the PR, @PolNavarro is the owner, I simply reviewed it.
But as @PolNavarro said, I'd prefer to have it in the same repo too.

[egelhaus]

An pre-built docker image via GitHub CI pushed to GHCR would also make sense.

[steffjenl]

As a software developer, I also prefer having everything in the same repository as the software. But from the perspective of a non-developer or a system administrator, what would I want to do with the source code? In that case, I’d rather have a clean repository containing just a docker-compose.yml and a Kubernetes deployment file.

I also prefer using a pre-built image. Today, I cleaned up my PR a bit because it still had some old commits from version 2.4.
See: cachethq/Docker#434

My preference is to keep the webserver, scheduler, and workers separate so that in larger deployments (with many subscribers), you can scale out by running multiple workers.

The scheduler is separated because artisan schedule:run should only run on a single container to avoid duplicate task execution.

Ultimately, you’ll also want to create templates for Portainer, Coolify, etc., and that’s why having a separate repository is more practical than trying to cram everything into one.