How to correctly link php-fpm and Nginx Docker containers?

How to correctly link php-fpm and Nginx Docker containers?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How to correctly link php-fpm and Nginx Docker containers?

When orchestrating a PHP application inside a containerized environment, the most common stumbling block is establishing communication between the web server (Nginx) and the PHP processor (php-fpm). The specific scenario you are facing highlights a fundamental misunderstanding of how container networking works in Docker Compose versus traditional host networking.

In your current setup, you are attempting to pass the fpm service to the Nginx configuration using the legacy links directive:

nginx:
    build: .
    ports:
        - "80:80"
        - "443:443"
    volumes:
        - ./:/var/www/test/
    links:
        - fpm
fpm:
    image: php:fpm
    ports:
        - "9000:9000"

While the links keyword was historically used to automatically generate environment variables (like PHP_FPM_HOST) and update /etc/hosts, relying on it in modern Docker Compose versions is discouraged. More critically, your Nginx configuration explicitly uses an IP address that does not belong to the Docker network:

location ~ ^/.+\.php(/|$) {
    fastcgi_pass 192.168.59.103:9000;
    # ...
}

This is the root cause of your failure. The IP 192.168.59.103 implies you are trying to reach a machine on your physical LAN or an older, non-existent Docker bridge subnet. Since the php-fpm container is running locally in the same Docker network as Nginx, it is not accessible via that external IP.

The Correct Networking Approach

To resolve this, you must remove the links directive entirely and replace the hardcoded IP with a service name reference. In Docker Compose v2 and later, containers on the same network can resolve each other by their service names defined in the docker-compose.yml.

First, update your Nginx configuration to listen on the hostname of the PHP container:

location ~ ^/.+\.php(/|$) {
    # Replace the IP with the service name 'fpm'
    fastcgi_pass fpm:9000; 
    fastcgi_split_path_info ^(.+\.php)(/.*)$;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param HTTPS off;
}

You also need to ensure the Nginx container can actually resolve the hostname fpm. In Docker Compose, this is automatic if both services are defined in the same file and share a network. However, if you prefer to use the legacy links feature for backward compatibility or specific environment variable injection, the syntax must be preserved exactly as shown in your original YAML, but the underlying Nginx config must still change from IP to hostname.

Handling Ports and Volumes

Your docker-compose.yml exposes port 9000:9000 on the host for the php-fpm container:

fpm:
    image: php:fpm
    ports:
        - "9000:9000"

While this allows direct access to the FPM socket via TCP, it is generally unnecessary when using Nginx as a reverse proxy. Exposing the FPM port directly opens the PHP processor to potential abuse vectors if not strictly secured. It is cleaner practice to keep the FPM container unexposed and rely solely on the Nginx fastcgi_pass directive.

Additionally, your volume mount:

- ./:/var/www/test/

copies the entire project directory into /var/www/test. Ensure your default.conf inside the build context actually points to this path. If you are running from the project root, make sure the root directive in Nginx matches the mounted volume location exactly, or adjust the SCRIPT_FILENAME parameter accordingly.

Final Configuration Summary

Here is a streamlined version of your setup that removes the dependency on external IPs and relies on Docker's internal DNS:

docker-compose.yml

version: '3'

nginx:
  build: .
  ports:
    - "80:80"
    - "443:443"
  volumes:
    - ./:/var/www/test/

fpm:
  image: php:fpm
  # Remove the ports line unless you have a specific need for direct FPM access

Nginx Config (default.conf)

server {
    listen  80;
    server_name localhost;
    
    root /var/www/test;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php(/|$) {
        fastcgi_pass fpm:9000;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param HTTPS off;
    }
}

By switching from an external IP to the service name fpm, you align your Nginx configuration with Docker's internal networking model. This ensures that when a request hits port 80, Nginx successfully proxies PHP requests to the php-fpm container without needing manual host file entries or static IP mappings.

Our network