Nginx and PHP-FPM

Use this guide when you chose Nginx for a native Ubuntu or Debian installation. Use Apache instead if that is the web server you selected. Never run both on the same HTTP ports.

1. Install Nginx and PHP-FPM

If you have not installed the packages yet, use the tab for your operating system:

sudo apt update
sudo apt install -y nginx php-cli php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-intl php-bcmath
sudo systemctl enable --now nginx

sudo apt-get update
sudo apt-get install -y nginx php-cli php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-intl php-bcmath
sudo systemctl enable --now nginx

Start the FPM service that matches your PHP version:

systemctl list-unit-files 'php*-fpm.service'
sudo systemctl enable --now php8.3-fpm

Replace php8.3-fpm with php8.4-fpm when that is the version installed on the server.

2. Create the Nginx site

Agovena includes a secure starting template. Copy it to Nginx and edit the hostname:

sudo cp /var/www/agovena/deploy/nginx.conf /etc/nginx/sites-available/agovena
sudo nano /etc/nginx/sites-available/agovena

Set these values in the file:

server_name store.example;
root /var/www/agovena/public;

Enable the site and remove the default site so Nginx does not serve the wrong document root:

sudo ln -s /etc/nginx/sites-available/agovena /etc/nginx/sites-enabled/agovena
sudo rm -f /etc/nginx/sites-enabled/default

The document root must end in /public. Never use /var/www/agovena as the root. The supplied template also denies .env, Composer files, the artisan file, hidden files and PHP execution under public storage. Keep those rules.

3. Match the PHP-FPM socket

List the sockets that exist on this server:

ls -l /run/php/php*-fpm.sock

Open the Nginx site file and make fastcgi_pass match the running PHP-FPM socket:

location ~ \.php$ {
    try_files $uri =404;
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_param DOCUMENT_ROOT $realpath_root;
}

Use the full supplied configuration, not only this excerpt. If you installed the optional Agovena FPM pool, use its socket instead:

/run/php/php8.3-fpm-agovena.sock

Nginx, PHP-FPM, the queue worker and cron must use the same application path and compatible runtime user. A 502 response usually means the FPM service, socket path or socket permissions are wrong.

4. Set permissions and upload limits

From the application directory, give the deployment user ownership and allow the www-data group to write runtime directories:

cd /var/www/agovena
DEPLOY_USER="${SUDO_USER:-$USER}"
sudo chown -R "$DEPLOY_USER":www-data /var/www/agovena
sudo chmod -R ug+rwX storage bootstrap/cache

The supplied template uses a 20 MB Nginx request limit. Keep it aligned with PHP:

upload_max_filesize = 20M
post_max_size = 20M

Do not use chmod 777, expose storage/app/private or create an alias for private files.

5. Enable HTTPS

Point DNS to the server and follow the HTTPS guide. After the certificate is active, set APP_URL to the HTTPS address and redirect HTTP to HTTPS. Do not collect administrator or customer credentials over plain HTTP.

6. Test and reload Nginx

Always test the configuration before reloading it:

sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl reload nginx

If the test fails, fix the reported file and line before reloading. Do not replace the complete security template with a minimal example.

7. Check the store

Open these URLs through the real hostname:

• /
• /login
• /admin
• a public product image under /storage
• a route that is not a physical file

Requests for .env, Composer files, artisan and private storage must not return their contents. Finish with the queue worker and scheduler guide.