Deployment Overview of WHMCS on Server¶

Prerequisites and Basic Requirements¶

To successfully deploy WHMCS on the server, the following environment requirements must be met:

Operating System: Linux distribution compatible with systemd (e.g., Ubuntu, Debian).
Privileges: Root access or sudo privileges are required for all installation and configuration steps.
Domain: A valid domain name (whmcs_domain) must be pointed to the server's IP address.
Ports: The following TCP ports must be open and accessible:
22 for SSH access.
80 for HTTP traffic and SSL certificate validation.
443 for HTTPS traffic.
Firewall: The Uncomplicated Firewall (UFW) is configured to allow traffic on ports 22, 80, and 443.

The application files and data are organized across the following directories:

Web Root: /var/www/html/whmcs
Contains the main WHMCS application files.
Includes index.php as the entry point.
Contains symbolic links for storage and downloads pointing to secure locations.
Secure Data Directory: /var/opt/whmcs/whmcs
Stores sensitive data outside the web root.
Contains the actual storage and downloads directories.
Configuration File: /var/www/html/whmcs/configuration.php
The main configuration file, renamed from configuration.sample.php.
PHP Session Directory: /var/opt/whmcs/php/session
Dedicated directory for PHP session storage.
Certbot Directory: /var/www/certbot
Used for ACME challenge validation during SSL certificate issuance.
SSL Certificates: /etc/letsencrypt/live/whmcs_domain/
Stores the fullchain.pem and privkey.pem files.
External Panel Directory: /opt/panel
Contains controlpanel.html downloaded from the external provider.

The WHMCS application is deployed using version 8.13.1. The installation process involves the following steps:

A temporary directory is created to handle the initial archive.
The archive whmcs_v8131_full.zip is transferred to the server.
The archive is extracted into the temporary directory.
The contents are moved to the final installation path /var/www/html/whmcs.
The configuration.sample.php file is renamed to configuration.php to prepare for configuration.
The install directory remains present until the web-based installation wizard is completed.

Additionally, the HostkeyResellerMod module is installed by cloning the repository and copying specific components:

Hooks are copied to /var/www/html/whmcs/includes/hooks/.
Server modules are copied to /var/www/html/whmcs/modules/servers/hostkeyresellermod/.
Addon modules are copied to /var/www/html/whmcs/modules/addons/hostkeyresellermod/.
Gateway callback files are copied to /var/www/html/whmcs/modules/gateways/callback/.

Security is enforced through firewall rules and strict file permissions:

Firewall: UFW is enabled and configured to allow only SSH (22), HTTP (80), and HTTPS (443).
User Accounts:
A system user whmcs is created with a home directory at /var/opt/whmcs.
The web server user www-data is used for ownership of web-accessible files.
File Permissions:
The main application directory /var/www/html/whmcs is owned by www-data:www-data with mode 0755.
The secure data directory /var/opt/whmcs/whmcs is owned by www-data:www-data with mode 0750.
The storage and downloads directories within the secure location are owned by www-data:www-data with mode 0750.
Symbolic links for storage and downloads in the web root are created and their ownership is explicitly set to www-data:www-data using chown -h.
The configuration.php file is set to mode 0640 to prevent world-readable access.
The PHP session directory is owned by www-data:www-data with mode 0750.

Nginx is configured to serve the WHMCS application with the following features:

HTTP to HTTPS Redirection: All HTTP traffic on port 80 is redirected to HTTPS.
SSL Configuration:
Uses certificates from Let's Encrypt located at /etc/letsencrypt/live/whmcs_domain/.
Includes secure SSL options and DH parameters.
Proxy Configuration:
Specific locations for controlpanel.html, /controlpanel/, /static/, /favicon.ico, /auth.php, /eq.php, /net.php, and /eq_callback.php are proxied to https://panel.hostkey.ru.
The /invapi/ location is proxied to https://invapi.hostkey.ru.
Headers Host, X-Real-IP, X-Forwarded-For, and X-Forwarded-Proto are set for proxied requests.
PHP Processing:
PHP files are processed by PHP-FPM via the socket /var/run/php/php8.3-fpm.sock.
Includes fastcgi-php.conf and fastcgi_params.
Configured with increased buffer sizes and read timeouts.
Security Rules:
Direct access to sensitive directories (crons, resources, vendor, includes, storage) is denied.
Access to .env, .ht*, .tpl, and phpunit.phar files is blocked.
Certbot Verification: A location block for /.well-known/acme-challenge/ is configured to allow certificate validation.

A dedicated MySQL database is created for WHMCS:

Database Name: whmcs_db
User: whmcs_user
Password: Stored securely in Ansible Vault (not visible in the playbook).
Privileges: The user is granted all privileges on the whmcs_db database.
Initialization: The database is created, the user is added, and privileges are granted before the application installation.

The following services are managed to ensure the application runs correctly:

Log Files: Nginx and PHP-FPM logs are monitored for errors and performance issues.
Certificate Renewal: Certbot is configured to automatically renew SSL certificates.
Backup Strategy: Regular backups of the database and application files are recommended.
Updates: The WHMCS application and modules should be updated regularly to patch security vulnerabilities.

Common issues and their resolutions:

SSL Certificate Errors: Ensure the domain is correctly pointed to the server and ports 80/443 are open. Check Certbot logs.
Permission Denied: Verify file ownership and permissions, especially for storage and downloads directories.
PHP Errors: Check PHP-FPM logs and ensure the correct PHP version is installed and configured.
Database Connection Errors: Verify database credentials in configuration.php and ensure the MySQL service is running.
Proxy Errors: Check Nginx configuration for proxy settings and ensure the external services (panel.hostkey.ru, invapi.hostkey.ru) are accessible.

This overview provides a comprehensive understanding of the WHMCS deployment, covering all aspects from prerequisites to maintenance.