The Complete NGINX on Ubuntu Series: Part 4A – PHP-FPM Installation and Setup

Welcome to Part 4A of our NGINX on Ubuntu series! We’re integrating PHP-FPM with NGINX for dynamic content.

NGINX + PHP-FPM Architecture

NGINX communicates with PHP through FastCGI using PHP-FPM, offering better performance than Apache’s mod_php.

graph TD
    A[Client] --> B[NGINX]
    B --> C{File Type?}
    C -->|Static| D[Serve Direct]
    C -->|PHP| E[PHP-FPM]
    E --> F[Execute PHP]
    F --> B --> A
    
    style B fill:#e1f5fe
    style E fill:#e8f5e8

Installing PHP-FPM

# Install PHP 8.3 and FPM
sudo apt update
sudo apt install php8.3 php8.3-fpm php8.3-mysql php8.3-curl php8.3-gd -y

# Start services
sudo systemctl start php8.3-fpm
sudo systemctl enable php8.3-fpm
sudo systemctl status php8.3-fpm

Create PHP Application

# Create directories
sudo mkdir -p /var/www/phpapp/{public_html,logs}
sudo chown -R www-data:www-data /var/www/phpapp

# Create simple index.php
echo "<?php echo 'PHP Version: ' . PHP_VERSION . '<br>Time: ' . date('Y-m-d H:i:s'); ?>" | sudo tee /var/www/phpapp/public_html/index.php

# Create info.php
echo "<?php phpinfo(); ?>" | sudo tee /var/www/phpapp/public_html/info.php

NGINX Configuration

# Create virtual host
sudo nano /etc/nginx/sites-available/phpapp.example.com

server {
    listen 80;
    server_name phpapp.example.com;
    root /var/www/phpapp/public_html;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        
        fastcgi_read_timeout 300;
        fastcgi_buffer_size 128k;
        fastcgi_buffers 256 16k;
    }
    
    location ~* \.(css|js|png|jpg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
    
    location ~ /\. {
        deny all;
        access_log off;
    }
    
    location ~* \.(htaccess|ini|log|sh|inc|bak)$ {
        deny all;
        access_log off;
    }
    
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    
    access_log /var/www/phpapp/logs/access.log;
    error_log /var/www/phpapp/logs/error.log;
}

Enable and Test

# Enable site
sudo ln -s /etc/nginx/sites-available/phpapp.example.com /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload NGINX
sudo systemctl reload nginx

# Add to hosts file
echo "127.0.0.1 phpapp.example.com" | sudo tee -a /etc/hosts

# Test PHP processing
curl -H "Host: phpapp.example.com" http://localhost/
curl -H "Host: phpapp.example.com" http://localhost/info.php

Troubleshooting

graph TD
    A[PHP Issues] --> B{Problem?}
    B -->|Downloads| C[Check PHP-FPM]
    B -->|502 Error| D[Check Socket]
    B -->|Permission| E[Fix Ownership]
    
    C --> F[systemctl status php8.3-fpm]
    D --> G[ls -la /var/run/php/]
    E --> H[chown www-data:www-data]
    
    style A fill:#ffebee
    style F fill:#e8f5e8
    style G fill:#e8f5e8
    style H fill:#e8f5e8

# Common fixes
sudo systemctl restart php8.3-fpm
sudo chown -R www-data:www-data /var/www/phpapp
sudo tail -f /var/www/phpapp/logs/error.log

# Monitor processes
sudo ps aux | grep php-fpm
php -m
sudo php-fpm8.3 -t

Key FastCGI Parameters Explained

• fastcgi_pass: Specifies PHP-FPM socket or TCP connection
• fastcgi_index: Default script when directory is requested
• SCRIPT_FILENAME: Full path to PHP script for execution
• fastcgi_buffer_size: Buffer size for reading response headers

Performance Monitoring

# Check PHP-FPM status
sudo systemctl status php8.3-fpm

# Monitor PHP processes
sudo ps aux | grep php-fpm

# Check socket connection
sudo ss -tulnp | grep php

# View real-time logs
sudo tail -f /var/www/phpapp/logs/access.log
sudo tail -f /var/log/php8.3-fpm.log

What’s Next?

You’ve successfully integrated PHP-FPM with NGINX! Your dynamic PHP applications are now running efficiently.

Coming up in Part 4B: PHP-FPM Optimization, Performance Tuning, and Advanced Configuration

References

• NGINX FastCGI Module
• PHP-FPM Documentation

This is Part 4A of our 22-part NGINX series. Part 4B covers optimization and advanced features. Questions? Drop them in the comments!