Installation Category · Part 1 of 4 System Requirements & Dependencies Pre-Flight Server Checklist
Server Requirements, PHP Extensions, File Permissions & Pre-Flight Dependencies
Before uploading or running the Keystone X Web Installer Wizard, review this complete pre-flight checklist covering supported operating systems, web servers (Apache, LiteSpeed, Nginx), PHP 8.1+ runtime extensions, php.ini memory and upload tuning, MySQL/MariaDB database engine requirements, outbound firewall ports, and mandatory directory write permissions.
1. Supported Hosting Environments & Hardware Specifications
Keystone X is engineered to run smoothly on standard Linux shared or business hosting (cPanel, DirectAdmin, Plesk), dedicated cloud VPS instances (Ubuntu, Debian, AlmaLinux, Rocky Linux on AWS, DigitalOcean, Hetzner, Xneelo, or Linode), or local Windows/macOS development stacks (AMPPS, XAMPP, Laragon, WampServer, MAMP).
| Deployment Scale | Concurrent Users | Minimum Server Spec | Recommended Production Spec |
|---|---|---|---|
| Small Business / Starter | 1 – 5 Staff Users | 1 vCPU · 1 GB RAM · 5 GB SSD | 2 vCPU · 2 GB RAM · 10 GB NVMe SSD (cPanel Business Hosting or Basic VPS) |
| Mid-Market / Multi-Warehouse | 5 – 25 Staff Users | 2 vCPU · 2 GB RAM · 20 GB SSD | 4 vCPU · 4 GB RAM · 40 GB NVMe SSD (Cloud VPS / Dedicated cPanel) |
| Enterprise / High-Volume ERP | 25+ Staff + Active Client Portal | 4 vCPU · 8 GB RAM · 50 GB SSD | 8 vCPU · 16 GB RAM · 100 GB NVMe SSD + Dedicated MySQL 8 InnoDB Buffer Pool |
2. Core Software Stack (Web Server, PHP & Database Engine)
| Component | Minimum Supported | Recommended Production | Critical Requirement Notes |
|---|---|---|---|
| Web Server | Apache 2.4+ or LiteSpeed | Apache 2.4+ / LiteSpeed Enterprise (or Nginx 1.22+ with Front-Controller rewrite) | Must have mod_rewrite enabled and AllowOverride All configured for .htaccess clean URL routing. |
| PHP Runtime | PHP 8.0.x | PHP 8.1, PHP 8.2, or PHP 8.3 | PHP 7.x is end-of-life and not supported (Keystone X uses modern PHP 8 typed properties, str_ends_with(), and strict exception handling). |
| Database Engine | MySQL 5.7+ or MariaDB 10.3+ | MySQL 8.0+ or MariaDB 10.6 / 10.11 LTS | Default storage engine must be InnoDB (required for ACID double-entry transactions) with utf8mb4_unicode_ci collation. |
| SSL / HTTPS Certificate | HTTP (Localhost Only) | Valid TLS 1.2 / 1.3 SSL Certificate (Let's Encrypt / Commercial SSL) | Required in production for secure session cookies, HTML5 mobile touch signature canvas, and encrypted Licensing Server handshakes. |
3. Mandatory PHP Extensions & Why Each Is Required
In cPanel (Select PHP Version → Extensions) or on your Linux VPS (apt install / dnf install), ensure the following PHP extensions are ticked and active before running the installer:
📸 SCREENSHOT PLACEHOLDER:
cpanel-php-version-and-extensions.png- Open cPanel → Software → Select PHP Version (or MultiPHP Manager).
- Show PHP 8.1 or PHP 8.2 selected, and open the Extensions tab showing
pdo_mysql,curl,gd,mbstring,zip,xml,intl, andfileinfochecked.
| PHP Extension | Requirement | Ubuntu / Debian CLI Package | What Fails If This Extension Is Missing? |
|---|---|---|---|
pdo & pdo_mysql |
Mandatory | php8.2-mysql |
Core database driver (app/config/database.php) and cron_runner.php cannot connect to MySQL/MariaDB. |
curl |
Mandatory | php8.2-curl |
Cannot communicate with the Keystone X Licensing Server (keystonex.co.za), check for OTA updates, dispatch remote diagnostics, or send Twilio WhatsApp messages. |
mbstring |
Mandatory | php8.2-mbstring |
Multi-byte UTF-8 string truncation (mb_strimwidth), PDF text encoding, and email subject encoding will fail. |
gd (or imagick) |
Mandatory | php8.2-gd |
Required by the PDF engine (dompdf / pdf_helper.php) to render your company logo, 1D/2D barcodes, and customer touch signatures onto Quotes, Invoices, and Job Cards. |
dom & xml |
Mandatory | php8.2-xml |
Required by the HTML-to-PDF rendering engine to parse document templates into print-ready A4 PDFs. |
zip |
Mandatory | php8.2-zip |
Required by the 1-Click Over-The-Air (OTA) Software Updater (update_pkg.zip extraction) and document bundle archives. |
openssl & hash |
Mandatory | Built into PHP Core | Required for TLS SMTP email encryption, SHA-256 Forensic Audit Log signing (AuditLogModel), and SHA-256 Backup Vault checksums (BackupModel). |
fileinfo |
Recommended | Built into PHP Core | Validates MIME types on uploaded Proof of Payment (POP) PDFs, supplier expense receipts, and company logos. |
intl |
Recommended | php8.2-intl |
Enhances international currency, locale, and date formatting. |
# One-Line Ubuntu / Debian PHP 8.2 Dependency Installer:
sudo apt update && sudo apt install -y php8.2 php8.2-cli php8.2-common php8.2-mysql php8.2-curl php8.2-gd php8.2-mbstring php8.2-xml php8.2-zip php8.2-intl libapache2-mod-php8.2
4. Recommended php.ini Configuration Directives
Because Keystone X generates multi-page PDF statements, processes CSV bank imports, and runs automated SQL snapshots, configure your php.ini (or cPanel MultiPHP INI Editor) with at least the following thresholds:
php.ini Directive |
Minimum Value | Recommended Value | Why This Matters |
|---|---|---|---|
memory_limit |
128M |
256M or 512M |
Prevents memory exhaustion when rendering high-resolution PDFs with embedded logos or generating full-database SQL snapshots. |
max_execution_time |
60 |
120 or 300 |
Ensures OTA software updates, batch PDF generation during cron runs, and large CSV imports never time out mid-operation. |
upload_max_filesize |
10M |
20M or 32M |
Allows uploading multi-page supplier invoices, customer POP documents, CSV catalogs, and ticket attachments. |
post_max_size |
12M |
32M or 64M |
Must always be equal to or larger than upload_max_filesize. |
max_input_vars |
1000 |
3000 or 5000 |
Required when saving large multi-line Quotes/Invoices or saving the Cross-Role RBAC Permission Matrix (admin/saveRoleMatrix). |
allow_url_fopen |
On |
On |
Required for local image and logo stream resolution inside PDF templates. |
5. Directory & File Write Permissions Matrix (chmod)
The web server user (www-data on Ubuntu/Debian, apache on AlmaLinux/RHEL, or your cPanel account user) must have Read & Write permissions (0755 on suPHP/cPanel or 0775 on standard Apache/Nginx) on the following paths:
| Relative Path from Project Root | Linux Permission | What Keystone X Writes Here |
|---|---|---|
/app/config/ |
0755 / 0775 |
The Web Installer writes config.php here, and the Licensing Engine writes and updates license.key here. |
/cache/ |
0755 / 0775 |
Stores encrypted license verification tokens (license.json), update metadata, and news feed cache files. |
/uploads/ (and subdirectories /uploads/pops/, /uploads/receipts/, /uploads/logos/) |
0755 / 0775 |
Stores uploaded company logos, favicons, Customer Proof of Payment (POP) attachments, Expense supplier slips, and digital Job Card signatures. |
/backups/ (or /app/backups/) |
0755 / 0775 |
Stores SHA-256 verified .sql database snapshots and the protective .htaccess lockdown file generated by the Backup Vault (BackupModel). |
/error.log (Project Root) |
0644 / 0664 |
Written by SystemErrorHandler.php to capture diagnostic stack traces for 1-click Helpdesk reporting. |
/install/ (During Initial Setup Only) |
0755 / 0775 |
Allows the 1-Click Security Hardening button on user/login (UserController::deleteInstallDir) to automatically delete /install once setup is complete. |
6. Outbound Firewall & Network Connectivity Requirements
If your server sits behind a strict corporate firewall (e.g., AWS Security Groups, UFW, CSF, or SonicWall), ensure outbound traffic is permitted on the following ports:
- Outbound TCP Port
443(HTTPS) tohttps://keystonex.co.za: Mandatory for License Key validation (license_check.php), subscription tier/module sync, Over-The-Air (OTA) software updates, and automated support ticket diagnostics. - Outbound TCP Port
587(STARTTLS) or465(Implicit SSL/TLS): Required to connect to your outbound SMTP mail server (Microsoft 365, Google Workspace, Amazon SES, cPanel Mail, or SendGrid). - Inbound TCP Port
80(HTTP) &443(HTTPS): Standard web access for your staff and Client Self-Service Portal users.