WHMCS Installation on NGINX + PHP 8.3-FPM (Ubuntu/Debian)

This document describes how to install WHMCS using NGINX, PHP 8.3-FPM, ionCube Loader, and MySQL. It is based on an earlier Apache2-based tutorial, translated for an NGINX stack.

1. Install Required Packages

Install NGINX, MySQL Server, PHP 8.3-FPM and required PHP extensions. Run the following commands:

apt update

apt install nginx

apt install mysql-server

apt install php8.3-fpm php8.3-cli php8.3-common \
    php8.3-mysql php8.3-gd php8.3-mbstring php8.3-bcmath \
    php8.3-xml php8.3-curl php8.3-zip php8.3-gmp php8.3-intl \
    php8.3-soap

apt install phpmyadmin   # optional, for web-based MySQL management
ln -s /usr/share/phpmyadmin /var/www/whmcs/phpmyadmin # expose phpmyadmin

phpenmod mbstring
systemctl restart php8.3-fpm

2. Install ionCube Loader for PHP 8.3-FPM

Download and install the ionCube loader:

cd /tmp
wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar -xzvf ioncube_loaders_lin_x86-64.tar.gz

# Copy the PHP 8.3 loader to the correct directory
cp ioncube/ioncube_loader_lin_8.3.so /usr/lib/php/20230831/

Edit the PHP configuration files for both CLI and FPM to load ionCube. Add the zend_extension line near the top of each file.

nano /etc/php/8.3/cli/php.ini
nano /etc/php/8.3/fpm/php.ini

zend_extension = /usr/lib/php/20230831/ioncube_loader_lin_8.3.so

Restart PHP-FPM:

systemctl restart php8.3-fpm

3. Create MySQL Database and User

Log into MySQL and create the database and user for WHMCS:

mysql

CREATE DATABASE whmcs;
CREATE USER 'whmcsuser'@'127.0.0.1' IDENTIFIED BY 'z9uYDMjN3bsKcWCfth42JwnBG5Xg6AeSPLE8mqvR';
GRANT ALL PRIVILEGES ON whmcs.* TO 'whmcsuser'@'127.0.0.1';
FLUSH PRIVILEGES;
\q

4. Create Document Root and Set Permissions

Create the WHMCS web root directory and assign proper ownership:

mkdir -p /var/www/whmcs
chown -R www-data:www-data /var/www/whmcs
chmod 755 /var/www

5. Configure NGINX for WHMCS

Create an NGINX server block for your WHMCS site. Replace yourdomain.com with your actual domain name.

nano /etc/nginx/sites-available/whmcs.conf

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    root /var/www/whmcs;
    index index.php index.html index.htm;

    # WHMCS friendly URLs
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # Static files
    location ~* \.(jpg|jpeg|gif|png|css|js|ico|svg|woff|woff2|ttf|eot)$ {
        try_files $uri $uri/ @rewrite;
        expires max;
        log_not_found off;
    }

    # Fallback for routes
    location @rewrite {
        rewrite ^/(.*)$ /index.php?rp=/$1 last;
    }

    # PHP handling
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Deny access to sensitive directories
    location ~^/(vendor|storage|resources)/ {
        deny all;
    }

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

Enable the WHMCS site and reload NGINX:

ln -s /etc/nginx/sites-available/whmcs.conf /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

If you are using HTTPS with Let's Encrypt, configure SSL certificates and add a server block that listens on port 443 with ssl and http2.

6. Optional: Disable OPcache (Troubleshooting)

Normally WHMCS works with OPcache enabled. If you encounter unexpected issues during installation, you may temporarily disable OPcache for PHP-FPM:

nano /etc/php/8.3/fpm/php.ini

opcache.enable=0

Restart PHP-FPM after changes:

systemctl restart php8.3-fpm

7. Configure WHMCS Cron Jobs

Set up the WHMCS cron jobs so that invoices, reminders and other tasks run automatically.

crontab -e

*/5 * * * * /usr/bin/php -q /var/www/whmcs/crons/cron.php
*/5 * * * * /usr/bin/php -q /var/www/whmcs/crons/pop.php

8. Upload WHMCS Files and Set Permissions

Upload the WHMCS distribution ZIP file to /var/www/whmcs (for example via SFTP), then extract it and fix file permissions:

apt install unzip

cd /var/www/whmcs
unzip whmcs_v8.x_full.zip
chown -R www-data:www-data /var/www/whmcs

During installation, WHMCS will request certain files and directories to be writable. For example:

chmod 777 configuration.php    # before installation
# After installation completes:
chmod 444 configuration.php

9. Run the WHMCS Web Installer

Open your browser and visit the WHMCS installer URL. Adjust the domain accordingly:

http://yourdomain.com/install/

Follow the on-screen steps:

• Confirm ionCube Loader is detected.
• Enter database details:
  • Database Name: whmcs
  • Username: whmcsuser
  • Password: PASSWORD
• Create your WHMCS admin account.
• After installation, delete or rename the /install directory for security.

10. Quick Reference: Apache vs NGINX Steps

SFTP Access: Allow Normal User to Upload Files to /var/www/whmcs

To allow your regular Linux user to upload WHMCS files via SFTP while keeping correct NGINX/WHMCS permissions, follow these steps:

1. Add your user to the www-data group

sudo usermod -aG www-data youruser

2. Set correct group ownership on the WHMCS web directory

sudo chown -R www-data:www-data /var/www/whmcs

3. Allow group write permissions

This ensures your SFTP user (now part of www-data) can upload or edit files:

sudo chmod -R 775 /var/www/whmcs

After applying these changes, log out and back in so the new group membership takes effect.