Arahoster AI Ultimate Tools — Installation Guide

Complete step-by-step installation, configuration, and verification guide for the Arahoster AI Ultimate Tools WHMCS addon module.

1. System Requirements
2. Pre-Installation Checklist
3. Installing ionCube Loader
4. Uploading the Module
5. Setting File Permissions
6. Activating the Module in WHMCS
7. Granting Admin Role Access
8. Initial Configuration
9. Configuring AI Providers
10. Configuring Cron Jobs
11. Enabling Optional Features
12. Client Area Setup
13. License Activation (Optional)
14. Verification & Smoke Tests
15. Troubleshooting
16. Upgrading
17. Uninstalling
18. Database Tables Reference
19. File Layout Reference
20. Support

The following PHP extensions must be enabled:

• curl
• json
• mbstring
• openssl
• pdo_mysql
• ionCube Loader (v13+)

Check on the server with:

php -m | grep -Ei 'curl|json|mbstring|openssl|pdo_mysql|ionCube'
php -v

The module makes HTTPS calls to:

• api.deepseek.com (default AI provider)
• api.openai.com (optional)
• api.anthropic.com (optional)
• generativelanguage.googleapis.com (Gemini, optional)
• ip-api.com / ipapi.co / ipinfo.io (country filter, optional)
• Your configured License Server endpoint (optional)

Whitelist these on firewalls / outbound proxies. Port 443/TCP.

Before you start, make sure you have:

•  Full backup of the WHMCS database and the /whmcs/ directory.
•  WHMCS admin account with Full Administrator permissions.
•  SSH or SFTP access to the WHMCS server.
•  Root or sudo access (only needed if installing ionCube).
•  Your AI provider API key ready (DeepSeek recommended).
•  (Optional) Your license key if you purchased a commercial plan.

Always test on a staging copy first. This module creates ~15 new database tables and adds hooks to many WHMCS events.

The module is encoded with ionCube and requires ionCube Loader v13+.

In WHMCS go to System Settings → System Health → PHP Info and search for ionCube. Or from CLI:

php -v
# Look for a line like:
# with the ionCube PHP Loader (enabled) + ionCube24 v13.x.x

If the version is 13 or higher, skip to section 4.

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

# Find the active PHP extension directory:
PHP_EXT=$(php -i | grep ^extension_dir | awk '{print $3}')

# Find the loader matching your PHP version:
PHP_VER=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
sudo cp ioncube/ioncube_loader_lin_${PHP_VER}.so "$PHP_EXT/"

# Find the active php.ini:
PHP_INI=$(php -i | grep "Loaded Configuration File" | awk '{print $5}')
echo "zend_extension = ${PHP_EXT}/ioncube_loader_lin_${PHP_VER}.so" | sudo tee -a "$PHP_INI"

# Restart the web server / php-fpm
sudo systemctl restart php${PHP_VER}-fpm
sudo systemctl restart apache2   # or: nginx

• cPanel/WHM: WHM → Software → EasyApache 4 → Customize → PHP Extensions → enable ioncube for every PHP version that WHMCS uses, then provision.
• DirectAdmin: Use CustomBuild — ./build set ioncube yes && ./build php n.
• Plesk: Tools & Settings → Updates & Upgrades → Add Components → PHP versions → ionCube.

php -v

You must see ionCube v13 or later listed before continuing.

The module ships as a single directory:

arahoster_ai_ultimate_tools/

It must be uploaded to:

/path/to/whmcs/modules/addons/arahoster_ai_ultimate_tools/

1. Extract the archive locally.
2. Upload the entire arahoster_ai_ultimate_tools/ folder into /whmcs/modules/addons/.
3. After upload the path /whmcs/modules/addons/arahoster_ai_ultimate_tools/arahoster_ai_ultimate_tools.php must exist.

cd /path/to/whmcs/modules/addons/
# Example using scp from your workstation:
scp -r arahoster_ai_ultimate_tools/ user@server:/path/to/whmcs/modules/addons/

# Or via git on the server (private install):
git clone https://github.com/hassanalsaleh88/app.git /tmp/aiut
cp -r /tmp/aiut/modules/addons/arahoster_ai_ultimate_tools /path/to/whmcs/modules/addons/

ls /path/to/whmcs/modules/addons/arahoster_ai_ultimate_tools/
# Expected output:
# arahoster_ai_ultimate_tools.php
# assets/
# hooks/
# hooks.php
# lib/

Apply WHMCS-compatible permissions:

cd /path/to/whmcs/modules/addons/arahoster_ai_ultimate_tools/

# Ownership: match your WHMCS user (often www-data, apache, or your panel user)
sudo chown -R www-data:www-data .

# Directories: 755, files: 644
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;

If your panel uses a different web user (apache, nobody, nginx, domainname on DirectAdmin, psaadm on Plesk, etc.) substitute it for www-data above.

The module does not need writable files outside of WHMCS's own attachments/, downloads/, and templates_c/ paths.

1. Log in to WHMCS admin: https://your-whmcs.com/admin/.
2. Navigate to System Settings → Addon Modules (in older WHMCS: Setup → Addon Modules).
3. Locate Arahoster AI Ultimate Tools in the list and click Activate.
4. WHMCS will run the activation hook which:
   • Verifies ionCube Loader is present.
   • Creates ~15 database tables (all prefixed arahoster_ai_…).
   • Seeds default settings.
   • Runs an initial (offline-safe) license check.
5. A green "Arahoster AI Ultimate Tools activated successfully" banner will appear. If it fails, see Troubleshooting.

If you see "This file cannot be accessed directly" or a blank Activate button, ionCube Loader is missing or the wrong version. Return to section 3.

After activation, click Configure next to the module and grant access to the relevant admin roles:

1. Tick the boxes for the admin roles that should see the module. At minimum, tick Full Administrator.
2. Scroll down to verify the configuration fields are populated (they will be blank on first install — that is fine).
3. Click Save Changes.

A new top-bar entry Addons → Arahoster AI Ultimate Tools is now available.

Open Addons → Arahoster AI Ultimate Tools. The left sidebar shows:

Dashboard            Approval Queue
AI Brain             Department Config
Training Data        Canned Responses
AI Content Tools     CMS & SEO
Ticket Intelligence  Marketing Suite
Livechat & Support   Drip Sequences
Auto Ticket Reply    Security & Fraud
                     Billing & Finance
                     Optimization
                     AI Usage Logs
                     License
                     Settings

Go to Settings first. You can configure the same fields here that you saw in the WHMCS Configure dialog, but with more help text.

Mandatory fields on first install:

Click Save Settings.

1. Create an account at https://platform.deepseek.com/.
2. Generate an API key in API Keys.
3. In WHMCS → Settings:
   • AI Provider: deepseek
   • DeepSeek API Key: paste the key
   • DeepSeek Model: deepseek-chat (general), deepseek-reasoner (long-form reasoning), or deepseek-coder (code-heavy tickets).
4. Save.

• OpenAI API Key: from https://platform.openai.com/api-keys
• OpenAI Model: gpt-4o (recommended), gpt-4o-mini, gpt-4-turbo, or gpt-3.5-turbo.

• Anthropic API Key: from https://console.anthropic.com/settings/keys
• Anthropic Model: pick the model name supplied by Anthropic for your account. Defaults are populated.

• Gemini API Key: from https://aistudio.google.com/apikey
• Gemini Model: gemini-1.5-pro, gemini-1.5-flash, or gemini-2.0-flash.

Open AI Content Tools → Ask AI, type "Reply in one word: pong", and submit. If you receive a response from the model, the provider is wired up correctly.

The module uses WHMCS's existing cron — no extra cron entry is required. But verify that WHMCS's cron is running:

crontab -l | grep whmcs
# Should show something like:
# */5 * * * * php -q /path/to/whmcs/crons/cron.php

Hooks the module attaches to:

• DailyCronJob — license refresh, login-history garbage collection, auto-reply queue flush.
• AfterCronJob — auto-reply queue processed every cron tick (so delay- to-post is accurate to within one cron interval).

To verify after activation, trigger cron manually:

php -q /path/to/whmcs/crons/cron.php

Then open AI Usage Logs in the module — you should see entries.

Each major capability has a master switch in Settings:

In addition, deeper configuration lives in dedicated sidebar sections:

• Training Data — curated Q&A pairs the AI Brain prefers over generic RAG matches. Import/Export as JSON or CSV.
• Auto Ticket Reply — set delay, per-ticket cap, allowed departments, staff impersonation ID, signature, post-reply ticket status.
• Department Config — per-department prompt, default tone & language, auto-reply toggle, analyzer toggle, require approval toggle.
• Approval Queue — for departments with require approval = on, generated drafts land here for admin review before posting.
• Security & Fraud — seven sub-tabs:
  1. Event Log
  2. Login History
  3. IP Rules
  4. Country Restriction (allow/block lists + GeoIP provider)
  5. Login Guard & 2FA (email-based)
  6. Content Protection (right-click, copy, iframe)
  7. Fraud Config (disposable + free-email blocking)

When Enable AI Livechat is on, the widget appears automatically on every client-area page via the ClientAreaHeadOutput hook. No template edits are required for the default WHMCS Twenty-One theme.

If you use a heavily customised theme and the widget does not appear, ensure your theme's header.tpl (or _pageheader.tpl) still calls {$headeroutput} and {$headoutput}.

Clients can manage their own security settings at:

https://your-whmcs.com/index.php?m=arahoster_ai_ultimate_tools&action=security

If you want a menu entry, add the following to your theme's client navbar template (includes/menu.tpl or your theme's clientareaprimarynavbar.tpl):

<li>
  <a href="index.php?m=arahoster_ai_ultimate_tools&action=security">
    <i class="fas fa-shield-alt"></i> Account Security
  </a>
</li>

When email 2FA is enabled, the ClientLogin hook sets a session flag and the ClientAreaPage hook redirects to:

?m=arahoster_ai_ultimate_tools&action=2fa

until the emailed code is verified. No template editing required.

The module ships license-disabled by default — every feature is unlocked. You only need this section if you are subscribing to a commercial plan.

1. Go to Addons → Arahoster AI Ultimate Tools → License.
2. Paste your License Key.
3. Paste your License Server Endpoint (e.g. https://arahoster.com/api/license/verify).
4. Click Save & Verify.

The status banner will turn:

• Green / "License Valid" — features enabled per your plan.
• Blue / "Trial License" — features enabled until trial expires.
• Yellow / "Grace Period" — server unreachable, last good response is honoured for up to 7 days.
• Red / "Invalid" — wrong key or revoked.

Leave both fields blank to keep the module fully unlocked (correct behaviour for self-hosted / full-source-code installations).

The license is rechecked once every 24 hours via the daily cron and can be forced via the Refresh Now button.

After install, walk through this checklist:

•  Activation — green banner shown on module activate.
•  AI Provider — AI Content Tools → Ask AI returns a response.
•  Database — run SHOW TABLES LIKE 'arahoster_ai_%'; in your DB. You should see ~15 tables.
•  Hooks — open a test ticket as a client; in admin go to Ticket Intelligence — the ticket should have a row with sentiment / urgency / language inside 1-2 minutes.
•  Auto Reply — enable auto-reply on a test department, open a ticket from a client; after the configured delay the queue should post a reply.
•  Approval Queue — set Require Approval on a department; tickets should now land in the queue instead of being auto-posted.
•  Training Data — add a Q&A pair and ask the same question through Ask AI — the curated answer should appear in the response.
•  Security / Login History — log in as a test client; a row appears under Security & Fraud → Login History.
•  Country Restriction — temporarily block your own country and try to log in: should be blocked. Remove the block afterwards.
•  Content Protection — enable right-click block and verify on the client area home page.
•  License — if used, Refresh Now returns the correct plan.

The module was opened outside of WHMCS. This is expected — always reach it via the WHMCS admin UI.

ionCube is missing or below v13. Re-read section 3.

The activation tried to create a table but the DB user lacks CREATE/ALTER privileges, or the table already exists with a different schema from a previous version. Solutions:

-- Drop only if you are reinstalling from scratch (destroys data!):
DROP TABLE IF EXISTS arahoster_ai_settings;
-- repeat for each affected table

-- Or grant DDL privileges to the WHMCS DB user:
GRANT CREATE, ALTER, INDEX, DROP, REFERENCES
  ON your_whmcs_db.* TO 'whmcs_user'@'localhost';
FLUSH PRIVILEGES;

Then click Deactivate → Activate in the addon page.

The admin role you are logged in as was not granted access. Open System Settings → Addon Modules → Arahoster AI Ultimate Tools → Configure and tick the role(s).

Either the endpoint is mistyped, blocked by an outbound firewall, or the license server is offline. Behaviour during outage:

• If the last successful check was less than 7 days ago — status switches to Grace, features stay on.
• After 7 days — status drops to Invalid, all paid features lock.

Test reachability:

curl -v https://your-license-server.example/api/license/verify

Increase max_execution_time in php.ini to 120s, and the CURLOPT_TIMEOUT in lib/AI/*.php providers if you use the deepseek-reasoner model on long contexts.

Module-specific events: Sidebar → AI Usage Logs. WHMCS-level errors: System Settings → System Logs → Module Log / Activity Log.

1. Take a full backup (DB + files).
2. Upload the new version of arahoster_ai_ultimate_tools/ over the old directory (or rsync -a --delete from a clean copy).
3. In WHMCS go to Addons → Arahoster AI Ultimate Tools. The module will detect the new version and run …_upgrade(), which is idempotent.
4. Hard refresh the admin browser (Cmd-Shift-R / Ctrl-F5).
5. Re-run the smoke tests in section 14.

Database migrations are additive only — column adds are wrapped in idempotent ALTER … ADD COLUMN IF NOT EXISTS patterns where supported, or guarded with INFORMATION_SCHEMA checks. No data is destroyed during upgrade.

1. Addons → Arahoster AI Ultimate Tools — note any data you want to keep and export (Training Data has a JSON/CSV export, AI Usage Logs can be SQL-dumped).
2. Go to System Settings → Addon Modules → Deactivate. Your data is preserved by default.
3. To fully remove all data:

-- DESTRUCTIVE. Run only if you are sure.
DROP TABLE IF EXISTS
  arahoster_ai_settings,
  arahoster_ai_logs,
  arahoster_ai_tickets,
  arahoster_ai_brain_chunks,
  arahoster_ai_livechat,
  arahoster_ai_canned,
  arahoster_ai_blog,
  arahoster_ai_campaigns,
  arahoster_ai_fraud,
  arahoster_ai_training_data,
  arahoster_ai_auto_reply_queue,
  arahoster_ai_ticket_analysis,
  arahoster_ai_dept_config,
  arahoster_ai_login_history,
  arahoster_ai_client_security,
  arahoster_ai_login_2fa;

-- And remove any custom columns added to tblannouncements / tblknowledgebase
-- (if you used Content Tools' direct-publish features). The module does not
-- add columns to those tables, only inserts rows, so nothing is required
-- there.

4. Delete the directory:

rm -rf /path/to/whmcs/modules/addons/arahoster_ai_ultimate_tools/

All tables are utf8mb4_unicode_ci and use InnoDB.

arahoster_ai_ultimate_tools/
├── arahoster_ai_ultimate_tools.php     # WHMCS module entry point
├── hooks.php                           # Top-level hook registrations
├── assets/                             # CSS / JS / images
├── hooks/                              # Hook handlers
└── lib/
    ├── autoload.php                    # PSR-4 autoloader
    ├── Database.php                    # Migrations + settings helper
    ├── License.php                     # License gating
    ├── AI/
    │   ├── Brain.php                   # RAG orchestrator
    │   ├── Factory.php                 # Provider selector
    │   ├── DeepSeek.php
    │   ├── OpenAi.php
    │   ├── Anthropic.php
    │   └── Gemini.php
    ├── Modules/
    │   ├── TrainingData.php
    │   ├── ContentTools.php
    │   ├── AutoReplyEngine.php
    │   ├── TicketIntelligence.php
    │   ├── Tones.php
    │   ├── DepartmentConfig.php
    │   ├── Approvals.php
    │   ├── LoginGuard.php
    │   ├── CountryFilter.php
    │   ├── ContentProtection.php
    │   ├── TicketContext.php
    │   ├── ReplyEnhancer.php
    │   └── SecurityEngine.php
    ├── Admin/
    │   ├── Controller.php
    │   └── views/                      # Each sidebar section's template
    └── Client/
        ├── Controller.php
        └── views/                      # 2FA, security, chat templates

• Vendor: Arahoster — https://me.arahoster.com
• Issue tracker: open a private support ticket in your Arahoster client area (preferred — includes your license key).
• Email: [email protected]

When reporting a problem, please include:

1. WHMCS version (Help → About WHMCS).
2. PHP version and ionCube version (php -v).
3. Module version (top of Addons → Arahoster AI Ultimate Tools → Dashboard).
4. The exact error banner text or a screenshot.
5. The last 50 lines of whmcs/storage/logs/laravel.log if available.