Architecture Overview
v1.6.2 Enterprise
How the 4-Step Deployment Engine Works
The Keystone X Installer provisions your entire ERP environment in four deterministic phases without manual SQL imports or config editing:
Step 1 & 2 • Cloud Licensing
Port 443 HTTPS
Keystone X Licensing Cloud & Cryptographic Verification
Keystone X uses a 3-layer security architecture to validate your subscription tier and receive Over-The-Air (OTA) updates:
- Outbound HTTPS Endpoint: Your web server must be able to reach
https://keystonex.co.za over outbound TCP port 443. Use the Test Cloud Ping button to measure live TLS handshake latency.
- RSA-2048 Public Key (
app/config/keystonex_public.key): Verifies that license responses and module entitlements are genuinely signed by the Keystone X authority.
- Layer-3 Gateway (
license_check.php): Enforces runtime integrity and initializes the PDO database driver security token.
# Test outbound connectivity from SSH terminal:
curl -I https://keystonex.co.za
Step 1 • Runtime & Extensions
PHP 8.2 / 8.3
PHP 8.2+ Engine & Required Extensions
Ensure the following extensions are enabled in cPanel MultiPHP / PHP Selector, Plesk PHP Settings, or your server's php.ini:
pdo & pdo_mysql — Powers all runtime ACID ledger transactions and prepared statements.
mysqli — Powers the installer's state-machine SQL provisioner and full database backup engine.
curl & openssl — Required for 256-bit TLS licensing, SMTP encryption, and API webhooks.
mbstring, dom, xml, gd — Required by Dompdf to render corporate PDFs with embedded logos and UTF-8 currency symbols.
zip, fileinfo, json — Required for OTA updates, MIME upload security validation, and Theme Studio token storage.
# Recommended php.ini production values:
memory_limit = 256M
upload_max_filesize = 32M
post_max_size = 32M
max_execution_time = 120
Step 1 • Filesystem Permissions
chmod 0755
Writable Directories & Ownership
The web server user (www-data, apache, or your cPanel username) requires write access to four directories:
/app/config — Stores auto-generated config.php and license.key.
/uploads — Stores company logos (/brand), customer POPs (/pops), and expense receipts (/receipts).
/cache — Stores signed license telemetry caches and OTA staging packages.
/css — Allows the 4-Layer Theme Studio to recompile css/app.css on the fly.
chmod -R 0755 app/config uploads cache css
Step 2 • Database Provisioning
MySQL 8.0+ / MariaDB 10.4+
Creating Your Database in cPanel, Plesk, or CLI
Keystone X uses InnoDB tables with utf8mb4_unicode_ci collation for full international character support:
- cPanel Shared/Cloud Hosting: Open MySQL® Database Wizard → create a database & user → check ALL PRIVILEGES. Remember to include your cPanel prefix (e.g.
cpuser_keystonex) in both Database Name and Database User.
- Plesk Control Panel: Go to Databases → Add Database, create a user with Read and Write access, and use
localhost as the host.
- Live Connection Test: Click Test DB Connection in Step 2 to verify your credentials before launching the interactive 112-migration deployment console.
CREATE DATABASE keystonex_erp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON keystonex_erp.* TO 'kx_user'@'localhost' IDENTIFIED BY 'StrongPassword!';
FLUSH PRIVILEGES;
Step 3 • Super Administrator
Zero-Trust RBAC
Provisioning the Primary Owner Account
Step 3 creates User #1 in the users table and binds it to the admin Role-Based Access Control (RBAC) profile:
- Bcrypt Encryption: Your master password is hashed via PHP's native
password_hash(..., PASSWORD_DEFAULT) before touching the database.
- Post-Login Setup: After logging in, visit Settings → Company Settings to upload your corporate logo, configure VAT/Tax rates, set document prefixes, and customize your Theme Studio palette.
- Staff & Technician Roles: Create granular roles (Sales, Accounts, Field Technician, Warehouse) under Settings → Roles & Permissions.
Step 4 • Security & Cron Automation
Production Hardening
Post-Installation Hardening & Cron Orchestrator
Complete these final steps before opening your platform to staff and clients:
- 1. Remove
/install Directory: Delete or rename the /install folder via File Manager, FTP, or SSH immediately after Step 4.
- 2. Lock Configuration File: Set
app/config/config.php permissions to 0644 or 0640.
- 3. Configure Enterprise Automation Cron: Schedule the daily background orchestrator (Recurring Invoices, Overdue Reminders, Low-Stock Watchdog, Warranty Scanner & Daily Task Reminders) in cPanel Cron Jobs:
# Run daily at 06:00 AM server time:
0 6 * * * /usr/local/bin/php /home/username/public_html/cron.php >/dev/null 2>&1
Troubleshooting FAQ
Quick Fixes
Resolving Common Deployment Issues
- "Access denied for user" in Step 2: On cPanel/Plesk, ensure you added the user to the database in MySQL Databases → Add User to Database and ticked ALL PRIVILEGES.
- "Cloud Unreachable" on License Check: Verify that outbound port
443 is open in your server firewall and that curl + openssl extensions are active.
- Need Direct Engineering Support? Contact support@keystonex.co.za or visit the Keystone X Client Portal.