Adding a full docker setup to the Filament Mastery Starters

For a while, my starter kits didn't include any Docker configuration. The foundation was solid with auth, roles, MFA, Horizon, Logs Viewer, but the deployment side was left to whoever cloned the project.

That was a deliberate choice at first. Docker setups vary a lot depending on the infrastructure: some people use a reverse proxy, others have Cloudflare in front, some run on bare metal, others on managed platforms. I didn't want to ship something that would need to be ripped out immediately.

But over time I changed my mind. Here's why and what the process taught me.

The problem with "just configure it yourself"

Leaving deployment out of a starter kit sounds reasonable. In practice, it means every project starts with the same 4-6 hours of Docker work that never really changes.

Multi-stage Dockerfile. PHP-FPM config. Nginx with HTTPS. PostgreSQL and Redis wired up. Horizon and the scheduler running as proper services. Healthchecks everywhere so Docker knows when things are actually ready.

None of it is so complicated. But it's time-consuming, easy to get subtly wrong, and almost identical from one project to the next.

Once I admitted that, the question wasn't whether to include Docker, it was how to do it in a way that's actually useful without being too opinionated about production infrastructure.

What I ended up building

The setup I settled on covers the full local development stack:

• A multi-stage Dockerfile: separate stages for Composer dependencies, Node assets, and the final PHP-FPM image. Keeps the production image lean.
• Nginx with HTTP-to-HTTPS redirect and a self-signed certificate for local dev, already included, no setup needed.
• PostgreSQL and Redis as services with proper healthchecks.
• Horizon and the scheduler as dedicated services, not crammed into the main app container.
• A bootstrap service that runs php artisan migrate --force before the app starts.

The Dockerfile uses three stages to keep the final image as lean as possible:

FROM php:8.4-fpm-alpine AS composer_builder
# Install extensions, run composer install
# ...

FROM node:24-alpine AS node_builder
# Install npm dependencies, build Vite assets
# ...

FROM php:8.4-fpm-alpine AS php_fpm
# Final image, only what's needed to run
# Copy vendor/ from composer_builder
# Copy public/build/ from node_builder
# ...

Each stage does one thing. The final image never contains Composer, Node, or dev dependencies.

The full Dockerfile architecture with extensions, non-root user, Xdebug for local dev, is covered here: Production-Ready Docker Setup for Laravel Filament.

The bootstrap service

Running migrations on deploy is one of those things that sounds simple until you've had a deployment fail because the app started before the database was ready.

The pattern I use is a dedicated bootstrap service that exits when migrations succeed. The app service depends on it, so the app simply doesn't start until migrations are done.

bootstrap:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan migrate --force
  depends_on:
    db:
      condition: service_healthy
    # ...

app:
  image: ${APP_IMAGE}:${APP_VERSION}
  depends_on:
    bootstrap:
      condition: service_completed_successfully
    # ...

horizon:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan horizon
  depends_on:
    bootstrap:
      condition: service_completed_successfully
    # ...

scheduler:
  image: ${APP_IMAGE}:${APP_VERSION}
  command: php artisan schedule:work
  # ...

No SSH. No manual commands. No "did someone run the migrations?" before going live.

A word of honesty on this pattern: it works well for single-instance deployments, one VPS, one app container. If you're running multiple replicas or need strict zero-downtime guarantees, this approach has limits. Multiple bootstrap services running simultaneously can conflict, and the app will be briefly unavailable during migration. In those cases, migrations should be handled at the CI/CD pipeline level, before containers are deployed. That's a topic worth a dedicated article, and it's on the roadmap.

The full compose setup, volumes, healthchecks, network config, restart policies, is covered in detail here: Production-Ready Docker Compose for Laravel Filament.

What I deliberately left out

I didn't include a production-ready Nginx config. Not because it's hard to write, but because production environments vary too much.

Some projects sit behind Traefik. Others use Cloudflare in front. Some have real Let's Encrypt certificates managed externally, others use internal PKI. Shipping a "production" Nginx config that works for one setup and silently breaks another isn't helpful.

What I do ship is a docker-compose.example.yaml, clearly labeled as a starting point, not a drop-in solution. The dev config is complete and ready to use. The production side is documented, commented, and deliberately left for the developer to adapt.

I think that's the right balance for a starter kit. Give people enough to be productive immediately, without making decisions that belong to them.

What this changes for the starters

Both the Backend Starter and the Multipanel Starter now include the full Docker setup.

Copy the repo, copy .env.example, define your app key, rundocker compose up -d --build, then php artisan backend:setup, and you have a running panel with auth, roles, MFA, Horizon, and Logs Viewer, all in one go.

It's a meaningful improvement over "configure Docker yourself." Not because Docker is complicated, but because those 4-6 hours are better spent on the actual project.

Both starters are available with the Filament Mastery membership.

As always, if something doesn't work the way you'd expect or you'd approach it differently, let me know in the comments.