cachethq
Add Docker Support for Easy Installation and Deployment
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 extensionsdocker-compose.yml- Complete orchestration with app, database, and Redis services.env.docker.example- Template environment file for Docker deploymentDOCKER.md- Comprehensive documentation and setup instructions
Docker Configuration
docker/nginx/nginx.conf- Optimized Nginx configuration for Laravel/Filamentdocker/php/cachet.ini- PHP optimizations for productiondocker/supervisor/supervisord.conf- Process management for Nginx, PHP-FPM, and queue workersdocker/entrypoint.sh- Startup script with database migrations and caching
Why Docker Support?
- Simplified Installation - One command deployment instead of complex manual setup
- Consistent Environment - Same setup works across development, staging, and production
- Dependency Management - All required services (MySQL, Redis) included and configured
- Production Ready - Optimized for performance with proper security practices
- 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:
- app - Cachet application (Nginx + PHP-FPM)
- db - MySQL 8.0 database
- 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
@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?
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.
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.
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: https://github.com/cachethq/Docker/pull/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.
Great work on this PR — the Docker setup is clean and will make running Cachet much easier.
One idea you might consider for deployments that want stricter role separation (compose/Kubernetes): split the current entrypoint.sh into smaller, role-specific scripts (e.g. entrypoint-web.sh, entrypoint-worker.sh, entrypoint-scheduler.sh) plus a tiny top-level entrypoint.sh that can delegate.
That way, when someone wants to isolate web / workers / scheduler as separate services or pods, they can simply switch the entrypoint per service (or container) without touching the image or codebase. It also makes scaling and health checks per role more straightforward.
Again, thanks for the excellent work here!
Hello, this is great but I think the PR description is missing some instructions. I tried deploying Cachet locally and I get a 500 because the application key is not configured properly. Any suggestion?
# Generate application key
docker-compose exec app php artisan key:generate
# Generate application key docker-compose exec app php artisan key:generate
Thanks for the quick reply. Yes I did this and I still get a 500.
I worked around the issue by generating a key locally and setting it the .env file, but now I run into the following issue:
I am facing the same issue. Running php artisan vendor:publish --tag=cachet inside the app container fixes it
Something missing is also support for proxies in front, especially for the scheme (but also the remote ip)
e.g.
fastcgi_param HTTPS $http_x_forwarded_proto;
fastcgi_param HTTP_X_FORWARDED_PROTO $http_x_forwarded_proto;
Thanks @fzakfeld!
I am facing the same issue. Running
php artisan vendor:publish --tag=cachetinside the app container fixes it
This step needs to be in the Dockerfile then @PolNavarro. I created an admin user from the console to test further, but now I encounter the following issue when logging in through /dashboard/login:
Does anyone have a workaround or is this an issue with the current state of v3?
For me it worked after fixing another issue with livewire (php artisan livewire:publish). I might find some time to fix the container but not right now
I think I have been able to fix a large number of the issues and also addressed a few inconveniences. @PolNavarro I did create a PR for your branch. Please have a look. For me using the compose file now works flawlessly
https://github.com/PolNavarro/cachet/pull/1
