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

Step 1: Initial Server Setup

1.1 Update System

sudo apt update && sudo apt upgrade -y

1.2 Set Timezone

sudo timedatectl set-timezone UTC
# Or your preferred timezone: sudo timedatectl set-timezone Asia/Dhaka

1.3 Create Swap (if RAM < 4GB)

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 Install Nginx

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

2.2 Install PHP 8.2 and Extensions

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

# Install PHP 8.2 and required extensions
sudo apt install -y php8.2-fpm php8.2-cli php8.2-common php8.2-curl \
    php8.2-mbstring php8.2-xml php8.2-zip php8.2-gd php8.2-bcmath \
    php8.2-pgsql php8.2-intl php8.2-readline php8.2-opcache

# Enable and start PHP-FPM
sudo systemctl enable php8.2-fpm
sudo systemctl start php8.2-fpm

# Verify PHP installation
php -v

2.3 Install Composer

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

2.4 Install PostgreSQL 16+

# Add PostgreSQL repository
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

# Install PostgreSQL 16
sudo apt install -y postgresql-16 postgresql-contrib-16

# Enable and start PostgreSQL
sudo systemctl enable postgresql
sudo systemctl start postgresql

# Verify installation
sudo -u postgres psql --version

2.5 Install pgvector Extension

# Install pgvector for PostgreSQL 16
sudo apt install -y postgresql-16-pgvector

# Verify installation
dpkg -l | grep pgvector

2.6 Install Additional Dependencies

# Install Git
sudo apt install -y git

# Install Supervisor (for queue workers)
sudo apt install -y supervisor
sudo systemctl enable supervisor
sudo systemctl start supervisor

# Install Tesseract OCR (👉 Tesseract Installation Guide)

sudo apt install -y tesseract-ocr tesseract-ocr-eng

# Install Poppler Utils
sudo apt install -y poppler-utils

# Install unzip and other utilities
sudo apt install -y unzip curl wget

Step 3: Setup PostgreSQL Database

3.1 Secure PostgreSQL

# Set PostgreSQL password
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'YourStrongPasswordHere';"

3.2 Create Database and User

sudo -u postgres psql << EOF
-- Create database
CREATE DATABASE helpnest_ai;

-- Create user
CREATE USER helpnest_user WITH ENCRYPTED PASSWORD 'YourSecurePassword123!';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE helpnest_ai TO helpnest_user;

-- Connect to database
\c helpnest_ai

-- Grant schema privileges
GRANT ALL ON SCHEMA public TO helpnest_user;

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Verify extension
\dx

-- Exit
\q
EOF

3.3 Configure PostgreSQL for Local Connections

# Edit pg_hba.conf
sudo nano /etc/postgresql/16/main/pg_hba.conf

Add/modify this line:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     md5
host    all             all             127.0.0.1/32            md5

Restart PostgreSQL:

sudo systemctl restart postgresql

Step 4: Setup Application Directory

4.1 Create Web Directory

sudo mkdir -p /var/www/helpnest-ai
cd /var/www/helpnest-ai

4.2 Upload Application Files

Option A: Upload ZIP via SCP

# From your local machine
scp helpnest-ai.zip root@your-server-ip:/var/www/

# On server
cd /var/www
unzip helpnest-ai.zip -d helpnest-ai
rm helpnest-ai.zip

Option B: Download from Remote URL

cd /var/www
wget https://yourdownloadurl.com/helpnest-ai.zip
unzip helpnest-ai.zip -d helpnest-ai
rm helpnest-ai.zip

Step 5: Set Proper Permissions

# Change ownership to www-data (Nginx user)
sudo chown -R www-data:www-data /var/www/helpnest-ai

# Set directory permissions
sudo find /var/www/helpnest-ai -type d -exec chmod 755 {} \;

# Set file permissions
sudo find /var/www/helpnest-ai -type f -exec chmod 644 {} \;

# Create required cache directories
sudo -u www-data mkdir -p bootstrap/cache
sudo -u www-data mkdir -p storage/framework/{cache,sessions,views}

# Set writable permissions for storage and cache
sudo chmod -R 775 /var/www/helpnest-ai/core/storage
sudo chmod -R 775 /var/www/helpnest-ai/core/bootstrap/cache

# Ensure www-data owns writable directories
sudo chown -R www-data:www-data /var/www/helpnest-ai/core/storage
sudo chown -R www-data:www-data /var/www/helpnest-ai/core/bootstrap/cache

After file upload, extraction, and permissions — complete setup via browser.

5.1 Access Installation Wizard

Open your browser
Visit: https://yourdomain.com(or http://your-server-ip if DNS not ready)
The installation wizard should load automatically.

5.2 License Verification

Enter your Envato Username
Enter your Purchase Code(from CodeCanyon → license.txt)
Click Verify & Next

5.3 Server Requirements Check

System checks:
PHP 8.2+
Extensions (bcmath, pdo_pgsql, gd, etc.)
PostgreSQL + pgvector

All green ✅ → Click Next
Any red ❌ → Fix missing items (see Step 2 & 3), then retry

5.4 Folder Permissions Check

Verifies write access:
core/storage/
core/bootstrap/cache/

All must be green ✅
If red: Run:bashsudo chmod -R 775 /var/www/helpnest-ai/core/storage
sudo chmod -R 775 /var/www/helpnest-ai/core/bootstrap/cache
sudo chown -R www-data:www-data /var/www/helpnest-ai/core/storage /var/www/helpnest-ai/core/bootstrap/cache
Click Next

5.5 Database Configuration

Enter details from Step 3:
Database Host: localhost
Database Port: 5432
Database Name: helpnest_ai
Database User: helpnest_user
Database Password: YourSecurePassword123!

Click Install Now

Installer will:
Import schema
Set up admin

5.6 Installation Complete

Wait for "Installation Complete!" message
Click:
Visit Site → https://yourdomain.com

5.7 Generate Chatbot Secret Key

Before using the app, you need to generate a secret key for the chatbot:

php artisan chatbot:generate-secret-key

Note: This secret key is critical. Keep it safe. If it is lost, all previously added domains for embedding the chatbot will need to be re-added with a new secret.

Step 6: Configure Nginx

6.1 Create Nginx Server Block

sudo nano /etc/nginx/sites-available/helpnest-ai

Add this configuration:

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    
    root /var/www/helpnest-ai/public;
    index index.php index.html;
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    
    # Max upload size
    client_max_body_size 100M;
    
    # Logging
    access_log /var/log/nginx/helpnest-ai-access.log;
    error_log /var/log/nginx/helpnest-ai-error.log;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        
        # Increase timeout for AI processing
        fastcgi_read_timeout 300;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
    }
    
    location ~ /\.(?!well-known).* {
        deny all;
    }
    
    # Cache static assets
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

6.2 Enable Site Configuration

# Create symlink
sudo ln -s /etc/nginx/sites-available/helpnest-ai /etc/nginx/sites-enabled/

# Remove default site (optional)
sudo rm /etc/nginx/sites-enabled/default

# Test Nginx configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Step 7: Setup SSL with Let’s Encrypt

7.1 Install Certbot

sudo apt install -y certbot python3-certbot-nginx

7.2 Obtain SSL Certificate

# Make sure DNS is pointed to your server first
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Follow prompts:

• Enter email address
• Agree to terms
• Choose to redirect HTTP to HTTPS (recommended)

7.3 Auto-Renewal Setup (already configured)

# Test renewal
sudo certbot renew --dry-run

Step 8: Setup Queue Workers with Supervisor

8.1 Create Supervisor Configuration

sudo nano /etc/supervisor/conf.d/helpnest-worker.conf

Add this content:

[program:helpnest-worker]
process_name=%(program_name)s_%(process_num)02d
command=/usr/bin/php /var/www/helpnest-ai/core/artisan queue:work --queue=ai_chat_processing,default --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/helpnest-ai/core/storage/logs/worker.log
stopwaitsecs=3600

8.2 Start Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start helpnest-worker:*

# Check status
sudo supervisorctl status

Step 9: Setup Cron Jobs

# Edit crontab for www-data user
sudo crontab -e -u www-data

Add these lines:

# Restart queue workers daily at 4 AM
0 4 * * * cd /var/www/helpnest-ai/core && php artisan queue:restart >> /dev/null 2>&1

Step 10: Post-Installation Verification

10.1 Test Website

1. Visit: https://yourdomain.com
2. Verify SSL certificate is active (padlock icon)
3. Test user registration and login

10.2 Test Admin Panel

1. Visit: https://yourdomain.com/admin
2. Login with default credentials
3. Configure Tesseract path: /usr/bin/tesseract
4. Test AI chatbot functionality

10.3 Verify Queue Processing

# Check if workers are running
sudo supervisorctl status

# Monitor queue in real-time
sudo -u www-data php artisan queue:monitor

Troubleshooting

Issue: 502 Bad Gateway

# Check PHP-FPM status
sudo systemctl status php8.2-fpm

# Check Nginx error logs
sudo tail -50 /var/log/nginx/helpnest-ai-error.log

# Restart services
sudo systemctl restart php8.2-fpm nginx

Issue: Permission Errors

sudo chown -R www-data:www-data /var/www/helpnest-ai
sudo chmod -R 775 /var/www/helpnest-ai/core/storage
sudo chmod -R 775 /var/www/helpnest-ai/core/bootstrap/cache

Issue: Database Connection Failed

# Test PostgreSQL connection
sudo -u postgres psql -d helpnest_ai -U helpnest_user -W

# Check PostgreSQL status
sudo systemctl status postgresql

# Verify .env database credentials

Issue: Queue Jobs Not Processing

# Check supervisor status
sudo supervisorctl status

# Restart workers
sudo supervisorctl restart helpnest-worker:*

# Check worker logs
tail -f /var/www/helpnest-ai/core/storage/logs/worker.log

Installation Complete! 🎉