Deployment Overview of WHMCS on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the following requirements must be met:

• Operating System: Ubuntu (based on package manager usage).

• Privileges: Root or sudo access is required for all installation steps.

• PHP Version: PHP 8.3 is required.

• Database: MySQL server must be installed and running.

• Domain/FQDN: A valid domain name pointing to the server IP is required for SSL certification via Certbot.

• Ports: The following TCP ports must be open:

• 22 (SSH)

• 80 (HTTP)

• 443 (HTTPS)

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a dynamically generated subdomain based on the server ID.

File and Directory Structure¶

The application uses a split directory structure to separate web files from sensitive data and storage:

• Web Root: /var/www/html/whmcs (Contains the main application files).

• Data Storage (External): /var/opt/whmcs/whmcs/storage (Symlinked to /var/www/html/whmcs/storage).

• Downloads Directory (External): /var/opt/whmcs/whmcs/downloads (Symlinked to /var/www/html/whmcs/downloads).

• PHP Session Data: /var/opt/whmcs/php/session.

• Nginx Configuration: /etc/nginx/sites-available/whmcs.

• SSL Certificates: /etc/letsencrypt/live/{whmcs_domain}/.

Application Installation Process¶

The installation follows a multi-step process involving dependency setup, database configuration, and file deployment:

1. System Dependencies: The system is updated to include essential packages such as nginx, mysql-server, certbot, git, and unzip.

2. PHP Environment Setup: PHP 8.3 and various extensions (php-fpm, php-mysql, php-gd, php-intl, etc.) are installed. The IonCube Loader is manually downloaded, extracted, and configured as a PHP extension for both CLI and FPM.

3. Database Setup: A MySQL database named whmcs_db is created with a dedicated user whmcs_user.

4. Application Deployment:

5. The application files are unpacked from a ZIP archive into /var/www/html/whmcs.

6. Configuration files are initialized by renaming configuration.sample.php to configuration.php.

7. Specialized directories (storage and downloads) are created outside the web root in /var/opt/whmcs/whmcs/ for security and then symlinked into the web root.

8. Module Integration: The Hostkey Reseller Mod is cloned from a Git repository and its hooks, modules, and gateway callback files are copied into the appropriate WHMCS directories.

Access Rights and Security¶

Security is enforced through several layers:

• User/Group Management: A dedicated whmcs user and group are created for system operations, while the web server (www-data) is granted ownership of the web root and specific data directories to ensure proper execution.

• Firewall (UFW): The Uncomplicated Firewall (UFW) is enabled with rules allowing traffic on ports 22, 80, and 443.

• Nginx Security Rules:

• Access to sensitive directories (crons, resources, vendor, includes, storage) is denied via Nginx configuration.

• Hidden files (e.g., .env, .ht) are blocked.

• Files with specific extensions like .tpl or PHPUnit files are restricted from direct access.

Databases¶

The application uses a local MySQL instance for data persistence.

Custom Scripts and Additional Setup¶

The following custom actions are performed during the deployment:

• Hostkey API Proxying: Nginx is configured to act as a reverse proxy for several endpoints (e.g., /auth.php, /eq.php, /net.php) pointing to panel.hostkey.ru.

• Control Panel Integration: A specific location block is created to proxy /controlpanel.html and its associated assets from the Hostkey panel.

• Cron Job Configuration: A system cron job is established to run the WHMCS maintenance script (cron.php) every 5 minutes using the PHP CLI.

• External Asset Download: The file controlpanel.html is downloaded from invapi.hostkey.ru and placed in /opt/panel.

Application Update Instructions¶

To update the main application:

1. Manual Method: Replace the files in /var/www/html/whmcs with the new version, ensuring that the configuration.php file is preserved and permissions are reset to www-data.

2. Service Restart: After updating files, it is recommended to restart the PHP-FPM service to clear any opcode caches:

   systemctl restart php8.3-fpm
   

Location of Configuration Files and Data¶

Available Ports for Connection¶

• HTTP: 80 (Redirected to HTTPS)

• HTTPS: 443

Starting and Stopping the Application¶

The application relies on Nginx and PHP-FPM. Use the following commands:

Nginx (Web Server):

• Start: systemctl start nginx

• Stop: systemctl stop nginx

• Restart: systemctl restart nginx

PHP-FPM:

• Restart: systemctl restart php8.3-fpm