VPS Installation Guide — Helpnest

Note

PostgreSQL with pgvector is required. This application relies on pgvector for AI embeddings and vector search. MySQL is NOT supported.

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
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 or modify these lines:

# 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

Step 6: Run Web-Based Installer

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

6.1 Access Installation Wizard

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

6.2 License Verification

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

6.3 Server Requirements Check

The system checks:

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

All green → Click Next. Any red → Fix missing items (see Steps 2 & 3), then retry.

6.4 Folder Permissions Check

Verifies write access to:

core/storage/
core/bootstrap/cache/

All must be green. If red:

sudo 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.

6.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. The installer will import the schema and set up the admin account.

6.6 Installation Complete

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

6.7 Generate Chatbot Secret Key

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

php artisan chatbot:generate-secret-key

Note

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

Step 7: Configure Nginx

7.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;
        fastcgi_read_timeout 300;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }

    location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}

7.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 8: Setup SSL with Let's Encrypt

8.1 Install Certbot

sudo apt install -y certbot python3-certbot-nginx

8.2 Obtain SSL Certificate

Make sure DNS is pointed to your server first.

sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Follow the prompts — enter your email, agree to terms, and choose to redirect HTTP to HTTPS (recommended).

8.3 Auto-Renewal (pre-configured)

# Test renewal
sudo certbot renew --dry-run

Step 9: Setup Queue Workers with Supervisor

9.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

9.2 Start Supervisor

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

# Check status
sudo supervisorctl status

Step 10: Setup Cron Jobs

10.1 Queue Restart (Recommended)

Edit the crontab for the www-data user:

sudo crontab -e -u www-data

Add this line to restart queue workers daily at 4 AM:

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

10.2 Laravel Task Scheduler (Required)

Add the scheduler cron entry in the same crontab:

# Laravel Task Scheduler
* * * * * cd /var/www/helpnest-ai/core && php artisan schedule:run >> /dev/null 2>&1

Step 11: Post-Installation Verification

11.1 Test Website

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

11.2 Test Admin Panel

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

11.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

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

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

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

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

Still stuck?

Our support team is ready to help you get set up.

Get support