Docker - how to set up Apache + PHP in docker-compose.yml
Migrating from an Nginx setup to Apache is a common requirement, especially when working with legacy projects or specific modules that rely on mod_php. If you are following a guide for Nginx and simply swapping the container name, you will quickly hit a wall: docker-compose syntax has evolved, and older tutorials often reference flags or structures that no longer exist in modern versions.
The most frequent stumbling block when attempting to replicate an Nginx setup with Apache is the handling of the PHP-FPM socket. Unlike Nginx, which can easily forward requests via a reverse proxy configuration file, Apache expects a specific environment to talk to the PHP process. In many older tutorials, you might see apache2 containers trying to connect to a Unix socket or a TCP port without properly exposing the PHP service first.
Consider the scenario where you have a working Nginx stack defined in your docker-compose.yml. You likely have a php service mapping volume ./code:/code and an nginx service listening on port 80. If you switch to Apache, you cannot just drop in an apache2:latest image expecting it to magically configure itself. The critical piece missing is the explicit connection mechanism between the web server and the PHP-FPM process.
A common error encountered during this transition involves the version key at the top of the file. In older Docker Compose specifications (version 1.x), the version field was optional but required if you were using specific syntax features. However, in version 2 and later, the version key is strictly deprecated for configuration purposes; it serves no functional role in defining services. Attempting to use it with modern parsers can sometimes lead to confusion, though usually, it just gets ignored. The real issue often arises when a guide suggests using a custom build context that does not exist locally.
For instance, if your docker-compose.yml references build: php, you must ensure a Dockerfile exists in a directory named php relative to your project root. Without this file, Docker Compose will fail with "Cannot locate specified Dockerfile." This is a frequent point of failure when copying configuration from online guides without the accompanying build context.
To set up Apache correctly, you generally need two distinct services: one for the PHP-FPM process and one for the Apache web server. The PHP service should expose the socket or listen on a TCP port, while the Apache container must be configured to pass traffic through to that endpoint. Using an image like webdevops/apache requires passing arguments to define the socket path, typically PHP_SOCKET=php:9000. This argument tells the Apache image where to find the PHP process.
Here is a robust pattern for defining these services in docker-compose.yml:
version: '3'
services:
php:
image: php:8.1-fpm
volumes:
- ./code:/var/www/html
# Exposing the socket allows Apache to connect
expose:
- "9000"
apache2:
image: webdevops/apache:latest
ports:
- "80:80"
volumes:
- ./code:/var/www/html
links:
- php
environment:
- PHP_SOCKET=php:9000
In this configuration, the links directive ensures that the Apache container can resolve the hostname php. The expose directive on the PHP service makes the socket available internally within the Docker network. By mounting the same ./code volume to both containers, you ensure that any file changes in your source directory are immediately reflected in both the web server and the PHP interpreter.
When migrating from Nginx, remember that while the volume mounting strategy remains similar, the internal communication protocol changes. Nginx often uses a static configuration file mounted at /etc/nginx/conf.d/site.conf, whereas Apache requires environment variables or specific arguments to initialize the correct FPM socket path. Always verify that your Dockerfile context exists if you are using a custom build, and ensure your docker-compose.yml adheres to the version constraints of your installed Docker Compose CLI.
