DEV Community

Andrés V
Andrés V

Posted on

Production-Ready CodeIgniter 4 + Docker Stack with CI/CD in Less than 10 Minutes

#php #codeigniter #docker #devops

The Problem Every PHP Developer Knows

You start a new CodeIgniter 4 project. Before writing a single line of business logic, you spend hours on setup: getting Docker to work, configuring Nginx, wiring PHP-FPM, setting up MySQL and Redis, making PHPUnit run inside the container, and then figuring out why your CI pipeline fails on the first push.

That setup time is dead time. It does not ship features. It does not impress clients.

And you do it again on the next project.

This article walks through the complete stack I built to solve that, and how it gets you from zero to a running, tested, production-ready CI4 environment in under 10 minutes.

The Stack

Component Version Role
PHP-FPM 8.2 FastCGI runtime
CodeIgniter 4.7 MVC framework + Shield auth
Nginx 1.28-alpine Reverse proxy, static files
MySQL 8.4 Primary database
Redis 7-alpine Cache, sessions, queue backend
Supervisor system PID-1 process manager in prod
PHPStan level 6 Static analysis, zero errors
Rector 1.x Automated PHP 8.2 refactoring
PHPUnit 10.5 Full test suite, pcov driver

Two Dockerfiles: Dockerfile.dev for local development with pcov and git support, Dockerfile for production with Supervisor as PID-1 and FastCGI healthcheck.

Up and Running in Under 10 Minutes

Unzip the files into your folder project:

# Build images, start containers, run migrations and seeders, verify health
make setup
Enter fullscreen mode Exit fullscreen mode

The make setup command does all of this in sequence: builds both images, starts all
containers, waits for MySQL and Redis to be ready, runs migrations, seeds the database, and hits the healthcheck endpoint to confirm everything is alive.

Verify the stack is healthy:

curl http://localhost:8080/health
Enter fullscreen mode Exit fullscreen mode

Expected response:

{
  "status": "ok",
  "database": "ok",
  "redis": "ok",
  "timestamp": "2026-06-26T15:00:00+00:00"
}
Enter fullscreen mode Exit fullscreen mode

If you see that JSON, the full stack is running: PHP-FPM, Nginx, MySQL, Redis, migrations applied, seeders executed.

Three Decisions That Are Not Obvious

1. Supervisor as PID-1, not php-fpm directly

Running php-fpm as PID-1 means zombie processes accumulate in long-running containers.

Supervisor handles signal forwarding correctly, reaps child processes, and restarts php-fpm if it crashes, without restarting the container.

2. Queue worker as a dedicated container

The queue worker runs as a separate container sharing the same image, not as a Supervisor program inside the web container. This means you can scale the worker independently, restart it without touching the web process, and read its logs in isolation.

3. pcov only in the dev image

pcov is a coverage driver. It has no place in a production image. The dev Dockerfile copies docker/php/pcov.ini into the image. The production Dockerfile does not.

This keeps the production image clean and avoids loading an extension that does nothing in that context.

The CI/CD Pipeline

Three quality gates run on every push and pull request:

jobs:
  tests:
    # PHPUnit full suite with pcov, coverage >= 20% enforced
  stan:
    # PHPStan level 6, zero errors required
  rector:
    # Rector dry-run, must exit clean
  ci-gate:
    # Blocks docker publish if any gate above failed
Enter fullscreen mode Exit fullscreen mode

No tag gets pushed without all three gates passing. The release.yml workflow validates the CHANGELOG entry for the version before creating the GitHub release.

Quality Gate Results (v1.1.4)

  • PHPStan level 6: 0 errors
  • Rector dry-run: clean
  • PHPUnit: 424 tests, 710 assertions
  • Lines coverage: 30.39% (gate minimum: 20%)

Three Configurations

The kit ships in three configurations depending on the infrastructure level you need:

Starter — Docker dev + prod, CI4 4.7, PHP 8.2, Nginx, MySQL 8.4, Redis 7, optimized Composer autoload, basic healthcheck endpoint.

Professional — Everything in Starter plus complete GitHub Actions CI/CD (ci/publish/release workflows), Sentry validated at runtime, Supervisor PID-1, FastCGI production-grade HEALTHCHECK, dedicated queue-worker container, full multi-tenancy layer, PHPStan level 6 + Rector.

Ultimate — Everything in Professional plus deployment guides for Railway, Render, and VPS Ubuntu, backup and restore scripts with 7-day rotation, production deploy scripts with rollback hint.

If you want to use the stack without building each piece from scratch, it is available here: CI4 Docker Premium Starter Kit

What stack are you running for local CI4 development?

Are you using Docker Compose, Laravel Valet, XAMPP, or something else entirely?
Drop it in the comments.

Top comments (0)