Integrating Apache with a PHP-FPM Container

🔰 Introduction

In many containerized environments, it’s common to run Apache in one container and PHP-FPM in another.
By default, an Apache container that serves only static files (HTML, CSS, JS) won’t execute PHP scripts because it lacks the PHP runtime.

If you’ve started a separate PHP-FPM container, you can configure Apache to forward all .php requests to the PHP-FPM service for processing.
This article explains how to set it up step by step.

---

🧩 Typical Scenario

Let’s assume you already have:

• An Apache container serving web content from /var/www/html
• A PHP-FPM container running PHP 8.x, accessible over the Docker network
  (for example, container name: php-fpm, listening on port 9000)
• Both containers connected to the same custom network, such as web-network

---

⚙️ Step 1 – Confirm the Network Connectivity

Ensure both containers are in the same network:

docker network inspect web-network

You should see both apache and php-fpm listed under Containers:.
If not, connect them manually:

docker network connect web-network apache
docker network connect web-network php-fpm

---

⚙️ Step 2 – Enable Apache Proxy Modules

In your Apache container, enable the required modules:

a2enmod proxy proxy_fcgi setenvif

Then restart Apache:

service apache2 restart

---

⚙️ Step 3 – Update Apache Virtual Host Configuration

Edit your Apache site configuration file, e.g. /etc/apache2/sites-available/000-default.conf
and add the following directives inside the <VirtualHost> block:

<VirtualHost *:80>
    ServerName example.local
    DocumentRoot /var/www/html

    <Directory "/var/www/html">
        AllowOverride All
        Require all granted
    </Directory>

    # Forward PHP requests to PHP-FPM container
    <FilesMatch "\.php$">
        SetHandler "proxy:fcgi://php-fpm:9000"
    </FilesMatch>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Explanation:

Directive	Description
SetHandler "proxy:fcgi://php-fpm:9000"	Tells Apache to pass all .php files to the PHP-FPM container (host:port).
php-fpm	The container name (or hostname) of your PHP-FPM service within the Docker network.
9000	Default listening port of PHP-FPM.

---

⚙️ Step 4 – Verify PHP-FPM is Accessible

From inside the Apache container, test connectivity:

apt install -y netcat
nc -vz php-fpm 9000

If successful, you should see:

Connection to php-fpm 9000 port [tcp/*] succeeded!

---

⚙️ Step 5 – Test with phpinfo()

Create a simple test file in your Apache document root:

echo "<?php phpinfo(); ?>" > /var/www/html/info.php

Then open your browser at:

http://<your-server-ip>/info.php

If everything is configured correctly, you should see the PHP Information page generated by PHP-FPM.

---

🧰 Optional: Docker Compose Example

Here’s a minimal docker-compose.yml example to define both containers in one file:

version: "3.9"
services:
  apache:
    image: httpd:2.4
    container_name: apache
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/local/apache2/htdocs/
      - ./apache-config.conf:/usr/local/apache2/conf/httpd.conf
    depends_on:
      - php-fpm
    networks:
      - web-network

  php-fpm:
    image: php:8.3-fpm
    container_name: php-fpm
    volumes:
      - ./html:/var/www/html
    networks:
      - web-network

networks:
  web-network:
    driver: bridge

---

✅ Summary

Component	Role	Note
Apache container	Handles HTTP requests	Forwards .php files to PHP-FPM
PHP-FPM container	Executes PHP code	Listens on port 9000
Docker network	Connects both containers	Use bridge or custom network

---

💡 Common Pitfalls

• File permission issues: ensure both containers mount the same volume and the www-data user has access.
• Wrong container name or port: SetHandler must point to the exact hostname and port exposed by PHP-FPM.
• Missing modules: double-check that mod_proxy, mod_proxy_fcgi, and mod_setenvif are enabled.

---

✅ In short:

To integrate Apache with a PHP-FPM container,
enable proxy_fcgi, configure SetHandler "proxy:fcgi://php-fpm:9000",
and ensure both containers share the same Docker network.