VPS Installation Guide

⌘K
  2. Home
  4. Docs
  6. BotMerze – AI Chatbot Saa...
  8. Instruction
  10. VPS Installation Guide

VPS Installation Guide

Database Requirements

  • Database Engine: PostgreSQL 16 or higher (required)
  • Extension: pgvector (must be installed and enabled)

⚠️ MySQL is NOT supported
This application relies on pgvector for AI embeddings and vector search.
This application is designed exclusively for PostgreSQL with pgvector.
MySQL cannot be used to set up or run this application under any circumstances.
Installation and configuration will fail if MySQL is used.

System Requirements

  • OS: Ubuntu 22.04 LTS or 24.04 LTS (recommended)
  • RAM: Minimum 2GB (4GB+ recommended)
  • Storage: Minimum 20GB
  • CPU: 2+ cores recommended
  • Root/Sudo Access: Required

This guide targets Ubuntu 22.04 / 24.04 LTS with Nginx + PHP-FPM. Apache, aaPanel, and CloudPanel notes are included where relevant.

Throughout this section the BotMerze install path is /home/<domain>/public_html, with index.php at root and Laravel at /home/<domain>/public_html/core.

Step 1 — Initial Server Setup

sudo apt update && sudo apt upgrade -y
sudo timedatectl set-timezone UTC   # or your local TZ, e.g. Asia/Dhaka

If RAM < 4 GB, create swap:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Step 2 — Install Required Software

2.1 Nginx

sudo apt install -y nginx
sudo systemctl enable --now nginx

Apache alternative: sudo apt install -y apache2 && sudo a2enmod rewrite headers

2.2 PHP 8.3 + Extensions

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

sudo apt install -y php8.3-fpm php8.3-cli php8.3-common php8.3-curl \
  php8.3-mbstring php8.3-xml php8.3-zip php8.3-gd php8.3-bcmath \
  php8.3-pgsql php8.3-intl php8.3-readline php8.3-opcache

sudo systemctl enable --now php8.3-fpm
php -v

2.3 Composer

cd ~
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

2.4 PostgreSQL 16

sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
  > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install -y postgresql-16 postgresql-contrib-16
sudo systemctl enable --now postgresql

2.5 pgvector

sudo apt install -y postgresql-16-pgvector
dpkg -l | grep pgvector

2.6 Other Dependencies

sudo apt install -y git supervisor tesseract-ocr tesseract-ocr-eng \
                    poppler-utils unzip curl wget
sudo systemctl enable --now supervisor

Install yt-dlp (video subtitle extraction — skip if you don’t use video knowledge sources):

sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp
yt-dlp --version

Step 3 — Configure PostgreSQL

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'StrongRootPass!';"

sudo -u postgres psql <<'EOF'
CREATE DATABASE botmerze;
CREATE USER botmerze_user WITH ENCRYPTED PASSWORD 'StrongAppPass!';
GRANT ALL PRIVILEGES ON DATABASE botmerze TO botmerze_user;
\c botmerze
GRANT ALL ON SCHEMA public TO botmerze_user;
CREATE EXTENSION IF NOT EXISTS vector;
\dx
EOF

In /etc/postgresql/16/main/pg_hba.conf allow local md5 auth:

local   all   all                  md5
host    all   all   127.0.0.1/32   md5

sudo systemctl restart postgresql

Step 4 — Upload Application Files & Install Dependencies

sudo mkdir -p /home/<domain>/public_html
cd /home/<domain>
# scp botmerze.zip root@SERVER_IP:/home/<domain>/
sudo unzip botmerze.zip -d public_html
sudo rm botmerze.zip

Install PHP dependencies (required before the app can boot):

cd /home/<domain>/public_html/core
sudo -u www-data composer install --no-dev --optimize-autoloader

Final layout:

/home/<domain>/public_html/
├── index.php
├── .htaccess
└── core/
    ├── vendor/          ← created by composer install
    ├── storage/
    ├── bootstrap/cache/
    └── .env

Step 5 — Permissions

sudo chown -R www-data:www-data /home/<domain>/public_html
sudo find /home/<domain>/public_html -type d -exec chmod 755 {} \;
sudo find /home/<domain>/public_html -type f -exec chmod 644 {} \;

sudo chmod -R 775 /home/<domain>/public_html/core/storage
sudo chmod -R 775 /home/<domain>/public_html/core/bootstrap/cache

Step 6 — Configure Nginx

See Nginx Configuration below for the full server block.

Step 7 — Free SSL

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
sudo certbot renew --dry-run

Step 8 — Run the Web Installer

With Nginx and SSL in place, open your browser and visit:

https://yourdomain.com

The BotMerze installer loads automatically. Walk through each screen:

  1. License Verification — enter your Envato Username and Purchase Code from CodeCanyon.
  2. Server Requirements — all items must show green. If any PHP extension is red, install it and reload.
  3. Folder Permissions — core/storage and core/bootstrap/cache must be writable (green). If not, re-run Step 5.
  4. Database Configuration — fill in the credentials created in Step 3:
    • Host: 127.0.0.1
    • Port: 5432
    • Database: botmerze
    • Username: botmerze_user
    • Password:
  5. Admin Account — set the admin name, email, and password you will use to log in.
  6. Click Install Now and wait for the success screen.

Step 9 — Post-Installation

Run these commands immediately after the installer completes:

Generate the Chatbot Secret Key

cd /home/<domain>/public_html/core
sudo -u www-data php artisan chatbot:generate-secret-key

⚠️ Keep this secret safe. Every chatbot domain is authorized against this key. If lost, all embedded chatbot deployments must be re-registered.

Optimize for Production

cd /home/<domain>/public_html/core
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache
sudo -u www-data php artisan event:cache
sudo systemctl reload php8.3-fpm

Configure Tesseract OCR Path

Go to Admin Panel → Settings → Chatbot & AI Settings → OCR & Tiktoken Settings.

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

Find the binary path after installation:

which tesseract

Paste the result (e.g. /usr/bin/tesseract) into the OCR path field and save.

Configure yt-dlp Path (optional)

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

which yt-dlp    # confirm path after installing, default: /usr/local/bin/yt-dlp

💡 Skip this if you do not plan to train the chatbot on video knowledge sources.

Step 10 — Queue Workers, Cron, Reverb

See:

Troubleshooting

# 502 Bad Gateway
sudo systemctl status php8.3-fpm
sudo tail -50 /var/log/nginx/botmerze-error.log
sudo systemctl restart php8.3-fpm nginx

# Permissions
sudo chown -R www-data:www-data /home/<domain>/public_html
sudo chmod -R 775 /home/<domain>/public_html/core/{storage,bootstrap/cache}

# DB
sudo -u postgres psql -d botmerze -U botmerze_user -W

# Queue
sudo supervisorctl restart botmerze-worker:*
tail -f /home/<domain>/public_html/core/storage/logs/worker.log
Was this article helpful to you? No Yes

How can we help?