Over the past few weeks we moved a PHP application that had been running on cPanel for years into containers. The goal was for the development, test and production environments to be built from the same definition, and for a new version to go out after a git push without any human intervention. In this article we describe how the solution is put together and the pitfalls we ran into, because those taught us the most.
What the system is made of
- Application: PHP-FPM and Nginx in separate containers, with Redis for sessions and Solr for search alongside them.
- Infrastructure repo: the Dockerfiles, the compose files and the pipeline live in a separate Git repository, not next to the application code.
- Build: GitLab CI builds the images and pushes them to the GitLab Container Registry.
- Runtime: Docker Compose stacks managed by Portainer.
- Traffic: Traefik receives the requests and obtains a Let’s Encrypt certificate for every environment.
- Database: runs on a separate server; the stack only connects to it.
A separate repo for the infrastructure
We deliberately did not put the Docker and CI definitions into the application’s repository. The main reason is separation of responsibilities: the development team owns the application repo, and we, the operations team, own the infrastructure repo. Everyone makes and approves changes in their own repo. The developers don’t have to deal with operational settings, and we don’t touch the application code.
The separation has practical benefits too. The application repo contains nothing but code, and operational changes get their own history: every change is a commit that can be reviewed and reverted.
This works because the Dockerfile and the build context don’t have to be in the same place. The pipeline fetches the application code and uses it as the context, and takes the Dockerfile from the infrastructure repo. The php.ini and the Nginx configuration come from a second, named context:
docker build \
--build-context infra=. \
-f docker/php-fpm/Dockerfile \
-t registry.example.com/app/php-fpm:dev-1a2b3c4 \
app
In the Dockerfile, COPY --from=infra refers to these files.
Pipeline: from push to running container
The application is on GitHub, and the build runs on GitLab. A plain GitHub webhook isn’t enough for this, because the two systems expect different formats. So a single small workflow in the application repo calls the GitLab trigger API and passes on the exact commit ID and the branch name. That way the pipeline is guaranteed to build the commit that was pushed.
Every image gets two tags:
- the branch name (
dev,test,prod), which always points to the latest build; - the branch name plus the short commit ID (
dev-1a2b3c4), which never changes.
After the build, the deploy step calls the environment’s Portainer webhook and passes the commit ID as a parameter:
curl --request POST "$WEBHOOK?APP_SHA=$APP_SHA"
The compose file builds the image tag from this:
image: registry.example.com/app/php-fpm:${ENVIRONMENT}${APP_SHA:+-${APP_SHA}}
At first we used only the branch name as the tag. It’s convenient, but it doesn’t tell you exactly which version is running, and rolling back is awkward. With the commit ID, the running version is unambiguous, and a rollback is just a redeploy with an earlier ID.
The webhook URL is different for each environment. GitLab’s environment-scoped variables handle this: the deploy job states which environment it deploys to, and GitLab passes the matching WEBHOOK value. So the pipeline contains a single variable name.
Several environments on one server
The environment is part of every name in the stack: the project, the containers, the network and the Traefik routes. That’s why dev and test run side by side on the same machine, behind the same Traefik, without any trouble. Only a few values differ per environment, such as the domain and the externally exposed ports.
Solr and the database are not reachable from the internet. Access to them is provided by a WireGuard VPN per environment: the client reaches only the necessary addresses through the tunnel, and all its other traffic takes the usual route.
What we ran into
Nginx didn’t even start. The regular expression in a rewrite rule contained {2}. Nginx interprets the curly brace as the start of a block, so such an expression has to be put in quotes.
The health check always reported an error. In an Alpine-based image, localhost resolved to an IPv6 address, but Nginx only listened on IPv4. The fix: 127.0.0.1 instead of localhost.
The scheduled tasks wouldn’t have run. The cron jobs are run by a separate container from the same image, with its own CPU and memory limits, so that it doesn’t take resources away from visitors. The scheduler, however, starts the tasks with a proc_open call, which php.ini disables for security reasons. So the cron container gets an additional setting that enables this function only there; on the web side the restriction stays.
The health endpoint returned 200 even when the database was unavailable. Only the text of the response indicated the error. Now it returns 503, so both the container status and external monitoring notice the problem.
The container logs grew without limit. Docker doesn’t rotate logs on its own. Every service got a size limit before the disk filled up.
The upload limit lives in two places. Raising the value in PHP was no use as long as Nginx’s lower limit rejected the request first. The two values have to be set together.
A directory ended up with the wrong owner. We store the data in the server’s /data/<environment>/ directories, so that backups are simple and a mistyped docker compose down -v can’t delete them. Along the way it turned out that every image that mounts an empty volume changes its owner, even if it mounts it read-only. So Nginx, which started later, took root ownership of one of the upload directories, and PHP could no longer write to it. The fix is the nocopy option on the read-only mounts.
Traefik wrote a security warning to the log. Because of a recent Traefik vulnerability (CVE-2026-88011), headers in the form X.Forwarded.For sent by the client reach the application untouched: Traefik treats them as separate headers, but PHP reads them as the same as the X-Forwarded-For header, so the client could forge the values set by the proxy. In our case, Nginx’s default configuration already dropped these, but we turned on filtering in Traefik as well (aliasHeadersStrategy), so that the protection doesn’t depend on a single default.
What we took away from this
- Test everything before it goes into production. Most of the problems above came to light not from the documentation, but from running the change on real containers.
- Implicit defaults are the most dangerous. Missing log rotation, volume ownership and a moving image tag all work fine until one day they don’t.
- A migration is also an inventory. The old environment quietly took care of a lot of things, such as sending mail and backups. In containers these need to be handled separately, so these gaps have to be mapped out in good time.
Today the system works like this: a pushed commit is running in the right environment a few minutes later, and at any time you can tell exactly which version is live. If you’re facing a similar migration and need help, get in touch.