⌘K

Installation Process

⚠️ Note: This section covers shared cPanel hosting the quickest path to get started. For production use, follow the VPS Installation Guide instead. Shared hosting cannot run Supervisor, which means queue workers and the Reverb WebSocket server must be driven by cron a fallback mode that adds latency to chat responses and is not suitable for high-traffic deployments.

This guide applies to shared cPanel hosting that already supports PostgreSQL 16 + pgvector.

Prerequisites Checklist

✅ PHP 8.3+ with all required extensions
✅ PostgreSQL 16+ with pgvector enabled
✅ Composer available via SSH/Terminal
✅ Tesseract OCR + Poppler Utils installed
✅ yt-dlp installed (optional — only needed for video knowledge sources)

Step 1 — Download & Extract

Download the BotMerze package from CodeCanyon.
Extract the ZIP. You’ll see two folders: Documentation/ and Installable File/.
Inside Installable File/, locate the main installable ZIP — this is what you upload to your server.

Step 2 — Create the PostgreSQL Database

cPanel → Databases → PostgreSQL Databases.
Create a database (e.g. botmerze).
Create a database user (e.g. botmerze_user) with a strong password.
Add the user to the database with ALL PRIVILEGES.

Database Name: botmerze
Database User: botmerze_user
Database Password: <your-strong-password>

Enable pgvector

\c botmerze
CREATE EXTENSION IF NOT EXISTS vector;
\dx

⚠️ If CREATE EXTENSION fails, ask your hosting provider to install postgresql-XX-pgvector.

Step 3 — Upload & Extract Files

Using cPanel File Manager or FTP:

Upload the installable ZIP into public_html (your domain root).
Right-click → Extract.

After extraction your structure should look like this:

public_html/
├── index.php          ← bootstrap entry (domain root)
├── .htaccess
└── core/              ← Laravel application
    ├── app/
    ├── bootstrap/
    ├── config/
    ├── database/
    ├── public/
    ├── resources/
    ├── routes/
    ├── storage/
    └── .env

Step 4 — Set Permissions

cd ~/public_html
chmod -R 755 core/storage core/bootstrap/cache

Step 5 — Run the Web Installer

Visit https://yourdomain.com — the installer auto-loads.
License verification — enter your Envato Username and Purchase Code.
Server requirements check — all items must be green.
Folder permissions check — all items must be green.
Database configuration:

Host:     localhost
Port:     5432
Database: botmerze
User:     botmerze_user
Password: <your-password>

Click Install Now and wait for the success screen.

Step 6 — Post-Installation

Generate the Chatbot Secret Key

cd /home/<user>/public_html/core
php artisan chatbot:generate-secret-key

⚠️ Keep this secret safe. If lost, every domain previously authorized to embed the chatbot must be re-registered with a new secret.

Configure OCR

Admin Panel → Settings → Chatbot & AI Settings → OCR & Tiktoken Settings, set the Tesseract path.

Install Tesseract by following the official guide: https://tesseract-ocr.github.io/tessdoc/Installation.html

After installation, find the binary path with:

which tesseract

Common locations: /bin/tesseract, /usr/bin/tesseract, /usr/local/bin/tesseract.

Configure yt-dlp (video knowledge sources)

Admin Panel → Settings → Chatbot & AI Settings → Video Settings, enable yt-dlp and set the path:

/usr/local/bin/yt-dlp

Set Up Cron Jobs (cPanel)

On shared hosting, cron is the only way to drive queue workers. Add all four entries — one for the scheduler and one per queue group:

# Laravel scheduler (drives all background tasks)
* * * * * cd /home/<user>/public_html/core && php artisan schedule:run >> /dev/null 2>&1

# AI chat queue — highest priority (chatbot replies, RAG, OpenAI calls)
* * * * * cd /home/<user>/public_html/core && php artisan queue:work --queue=ai_chat_processing --stop-when-empty --max-time=55 >> /dev/null 2>&1

# Default queue (embeddings, mail, webhooks)
* * * * * cd /home/<user>/public_html/core && php artisan queue:work --queue=default --stop-when-empty --max-time=55 >> /dev/null 2>&1

# Commerce sync queue (WooCommerce + Shopify + Generic API)
* * * * * cd /home/<user>/public_html/core && php artisan queue:work --queue=woocommerce,shopify,generic-api --stop-when-empty --max-time=55 >> /dev/null 2>&1

⚠️ Cron-tick workers are a fallback. Chat responses may lag up to 60 seconds and there is no persistent Reverb WebSocket server. Move to a VPS with Supervisor as soon as traffic grows — see VPS Installation Guide.

Troubleshooting

Issue	Fix
Installer page won’t load	Check `.htaccess` and folder permissions
Database connection error	Verify `core/.env` credentials
500 Internal Server Error	Set `core/storage` to 755, set `APP_DEBUG=true`, inspect `core/storage/logs/laravel.log`
`pgvector` not available	Ask host to install `postgresql-XX-pgvector`
Queue jobs stuck	Confirm cron is running

Was this article helpful to you? No Yes

Installation Process