Configuring Nginx

About 2 min

Configuring Nginx

Hazaar Framework works with Nginx for traditional web hosting environments. However, for modern production deployments, we recommend using FrankenPHP, which provides better performance, built-in HTTP/2 and HTTP/3 support, and advanced features like worker mode.

This guide covers Nginx configuration for scenarios where traditional hosting is required, such as shared hosting environments or existing Nginx infrastructure.

Prerequisites

Before deploying to Nginx, ensure you have created a Hazaar application. See the Getting Started guide for installation instructions.

Hazaar also works with Apache and other web servers, though FrankenPHP, Nginx, and Apache are the primary tested configurations.

PHP-FPM Installation

Unlike Apache with mod_php, Nginx requires PHP-FPM (FastCGI Process Manager) to process PHP files. Install it on your Debian-based system:

sudo apt-get install php-fpm

You can configure PHP-FPM by editing the php.ini file, typically located at /etc/php/8.0/fpm/php.ini (version number may vary depending on your PHP installation).

Directory Structure

Hazaar applications follow a standard MVC structure with a public directory that serves as the web-accessible entry point. See Project Layout for more details.

Server Block (Virtual Host)

The most common way to deploy a Hazaar application with Nginx is using a server block (Nginx's equivalent of Apache's virtual host). This provides better isolation and configuration control.

Example configuration:

server {
    listen 80;
    listen [::]:80;
    
    server_name myapp.example.com;
    root /home/user/myapp/public;
    index index.php;

    # Maximum upload size (adjust as needed)
    client_max_body_size 20M;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_param APPLICATION_ENV production;
    }

    # Deny access to hidden files
    location ~ /\. {
        deny all;
    }
}

Key directives:

Update server_name to match your domain
Update root to point to your application's public directory (created via composer create-project hazaar/hazaar myapp)
Adjust fastcgi_pass to match your PHP-FPM socket path (check /etc/php/ for your PHP version)
Set APPLICATION_ENV to your desired environment (production, development, etc.)

Save this configuration to /etc/nginx/sites-available/myapp and enable it:

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Document Root

If your Hazaar application is the only site running on your Nginx server, you can modify the default server block to point to your application's public directory.

Edit /etc/nginx/sites-available/default:

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    
    root /home/user/myapp/public;
    index index.php;

    server_name _;

    client_max_body_size 20M;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_param APPLICATION_ENV production;
    }

    location ~ /\. {
        deny all;
    }
}

Then reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Sub-Directory

To run your application in a sub-directory (e.g., http://yourdomain.com/myapp), add a location block to your existing server configuration:

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/html;
    index index.php index.html;

    # Other locations...

    location /myapp {
        alias /home/user/myapp/public;
        try_files $uri $uri/ @myapp;
        
        location ~ \.php$ {
            include snippets/fastcgi-php.conf;
            fastcgi_pass unix:/var/run/php/php-fpm.sock;
            fastcgi_param APPLICATION_ENV production;
            fastcgi_param SCRIPT_FILENAME $request_filename;
        }
    }

    location @myapp {
        rewrite /myapp/(.*)$ /myapp/index.php?/$1 last;
    }

    location ~ /\. {
        deny all;
    }
}

Warning

Sub-directory deployments are more complex with Nginx and may require additional configuration adjustments depending on your application's routing. Consider using a Server Block with a subdomain instead for better maintainability.

SSL/TLS Configuration

For production deployments, always use HTTPS. Here's an example with SSL (using Let's Encrypt):

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    
    server_name myapp.example.com;
    root /home/user/myapp/public;
    index index.php;

    # SSL certificates
    ssl_certificate /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/myapp.example.com/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    client_max_body_size 20M;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_param APPLICATION_ENV production;
    }

    location ~ /\. {
        deny all;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name myapp.example.com;
    return 301 https://$server_name$request_uri;
}

Common PHP-FPM Socket Paths

The fastcgi_pass directive varies depending on your system and PHP version. Common paths include:

Debian/Ubuntu: /var/run/php/php8.0-fpm.sock (or php8.1, php8.2, etc.)
Generic/symlink: /var/run/php/php-fpm.sock
Red Hat/CentOS: /var/run/php-fpm/www.sock

To find your PHP-FPM socket:

sudo find /var/run -name "*php*fpm*.sock"