HelpDesk Pro

Appearance

Installation Guide ​

Welcome to HelpDesk Pro! This comprehensive guide will walk you through installing your AI-powered customer support system. Choose the installation method that best fits your hosting environment and technical expertise.

📋 Table of Contents ​

System Requirements ​

🖥️ Server Requirements ​

ComponentMinimumRecommended
PHP8.2+8.3+
DatabaseMySQL 8.0+ / MariaDB 10.4+MySQL 8.0+
Web ServerApache 2.4+ / Nginx 1.18+Nginx 1.20+
Memory512MB RAM2GB+ RAM
Storage100MB free space1GB+ free space
SSLNot requiredHighly recommended

📦 Required PHP Extensions ​

Ensure these PHP extensions are installed and enabled:

  • ✅ BCMath - For precise mathematical calculations
  • ✅ Ctype - For character type checking
  • ✅ cURL - For HTTP requests and API calls
  • ✅ DOM - For XML/HTML processing
  • ✅ Fileinfo - For file type detection
  • ✅ JSON - For data serialization
  • ✅ Mbstring - For multibyte string handling
  • ✅ OpenSSL - For secure connections
  • ✅ PCRE - For regular expressions
  • ✅ PDO - For database abstraction
  • ✅ Tokenizer - For PHP parsing
  • ✅ XML - For XML processing

🛠️ Development Tools (VPS Only) ​

  • Node.js: 18.0+ (for frontend compilation)
  • Composer: Latest version (for PHP dependencies)
  • Git: For version control

Pre-Installation Checklist ​

Before starting the installation, ensure you have:

✅ Account Information ​

  • [ ] CodeCanyon purchase confirmation
  • [ ] Download link for HelpDesk Pro
  • [ ] Access to your hosting control panel

✅ Hosting Requirements ​

  • [ ] PHP 8.2+ installed and enabled
  • [ ] MySQL/MariaDB database available
  • [ ] Required PHP extensions enabled
  • [ ] Sufficient disk space (100MB+)
  • [ ] Domain name pointing to your server

✅ Database Information ​

  • [ ] Database host (usually localhost)
  • [ ] Database name
  • [ ] Database username
  • [ ] Database password
  • [ ] Database port (usually 3306)

✅ Admin Account Details ​

  • [ ] Admin username (choose a secure one)
  • [ ] Admin password (use a strong password)
  • [ ] Admin email address
  • [ ] Company information

Installation Methods ​

Choose the installation method that matches your hosting environment:

🏠 cPanel Installation (Beginner-Friendly) ​

Perfect for shared hosting users and beginners. This method uses cPanel's graphical interface and doesn't require command line access.

Step 1: Download and Prepare Files ​

  1. Download HelpDesk Pro

    • Log into your CodeCanyon account
    • Go to your downloads section
    • Download the latest version of HelpDesk Pro
    • Save the ZIP file to your computer

  2. Extract the Files

    • Right-click the downloaded ZIP file
    • Select "Extract All" or use your preferred extraction tool
    • You should see a folder named helpdesk-pro or similar
    • Note: Keep the extracted folder handy for the next steps

Step 2: Upload Files to cPanel ​

  1. Access cPanel File Manager

    • Log into your cPanel account
    • Find and click "File Manager" in the Files section
    • Navigate to public_html (or your domain's root folder)
    • Important: If you have multiple domains, select the correct domain folder

  2. Upload the Files

    • Click the "Upload" button in File Manager
    • Select all files and folders from the extracted HelpDesk Pro folder
    • Upload them to your domain's root directory
    • Critical: Upload files directly to public_html, not in a subfolder
    • Wait for the upload to complete (this may take a few minutes)

  3. Verify Upload

    • Check that all files are uploaded correctly
    • Look for folders like app, config, public, storage, etc.
    • If you uploaded a ZIP file, extract it in File Manager and delete the ZIP

Step 3: Set File Permissions ​

  1. Set Folder Permissions

    • Select the storage folder
    • Right-click and choose "Permissions"
    • Set permissions to 777 (read, write, execute for all)
    • Click "Change Permissions"

  2. Set Cache Permissions

    • Select the bootstrap/cache folder
    • Right-click and choose "Permissions"
    • Set permissions to 777
    • Click "Change Permissions"

  3. Set Other Folder Permissions

    • Select all other folders (except storage and bootstrap/cache)
    • Right-click and choose "Permissions"
    • Set permissions to 755
    • Click "Change Permissions"

Step 4: Create Database ​

  1. Access MySQL Databases

    • In cPanel, find "MySQL Databases" in the Databases section
    • Click to open the MySQL Databases interface

  2. Create Database

    • In the "Create New Database" section
    • Enter database name: helpdesk_pro (or your preferred name)
    • Click "Create Database"
    • Note: Your hosting provider may add a prefix to the database name

  3. Create Database User

    • Scroll down to "Add New User" section
    • Enter username: helpdesk_user (or your preferred name)
    • Enter a strong password (use the password generator)
    • Click "Create User"

  4. Add User to Database

    • In the "Add User to Database" section
    • Select the user you just created
    • Select the database you just created
    • Click "Add"
    • Check "All Privileges" in the privileges list
    • Click "Make Changes"

  5. Note Database Details

    • Write down the complete database name (with prefix)
    • Write down the complete username (with prefix)
    • Write down the password
    • You'll need these for the installer

Step 5: Run the Installation Wizard ​

  1. Access the Installer

    • Open your web browser
    • Navigate to https://yourdomain.com/install
    • Replace yourdomain.com with your actual domain name
    • Note: Use https:// if you have SSL, otherwise use http://

    You should see the HelpDesk Pro installer welcome screen:

    ┌─────────────────────────────────────┐
│        HelpDesk Pro Installer       │
│                                     │
│  Welcome to HelpDesk Pro Setup      │
│                                     │
│  [Check Requirements]               │
└─────────────────────────────────────┘

  2. System Requirements Check

    • Click "Check Requirements" to proceed
    • The installer will automatically check your server requirements
    • All items should show green checkmarks ✅
    • If any items show red X marks ❌, contact your hosting provider

    Required PHP Extensions Check:

    • ✅ PHP 8.2+ (or higher)
    • ✅ MySQL/MariaDB support
    • ✅ OpenSSL extension
    • ✅ PDO extension
    • ✅ Mbstring extension
    • ✅ Tokenizer extension
    • ✅ XML extension
    • ✅ Ctype extension
    • ✅ JSON extension
    • ✅ cURL extension

  3. File Permissions Check

    • Click "Check Permissions" to verify folder permissions
    • The following directories must be writable:
      • ✅ storage/ directory
      • ✅ bootstrap/cache/ directory
      • ✅ resources/lang/ directory
      • ✅ public/ directory
    • If any show red X marks, fix permissions as described in Step 3

  4. Purchase Code Verification

    • Enter your CodeCanyon purchase code
    • You can find your purchase code in your CodeCanyon downloads
    • Help: Where to find your purchase code
    • Click "Submit" after entering your purchase code

  5. Database Configuration

    • Database Host: Usually localhost
    • Database Port: Usually 3306
    • Database Name: Enter the complete database name (with prefix)
    • Database Username: Enter the complete username (with prefix)
    • Database Password: Enter the password you created
    • Click "Test Connection" to verify
    • Click "Submit" when connection is successful

  6. Admin Account Setup

    • Admin Username: Choose a secure username
    • Admin Password: Use a strong password (minimum 8 characters)
    • Admin Email: Enter your email address
    • Company Name: Enter your company name
    • Site URL: Should auto-populate with your domain
    • Click "Complete Setup" to finish

  7. Installation Complete

    • Review all settings
    • Click "Install HelpDesk Pro"
    • Wait for the installation to complete
    • You'll see a success message when finished
    • Important: Delete the install folder for security

Step 6: Post-Installation (cPanel) ​

  1. Delete Installer Files (Security)

    • In File Manager, navigate to your domain folder
    • Delete the install folder completely
    • This prevents unauthorized access to the installer

  2. Test Your Installation

    • Visit your domain to see the public ticket page
    • Log into the admin dashboard at https://yourdomain.com/admin
    • Create a test ticket to verify everything works
    • Check that email notifications are working

🖥️ VPS/Server Installation (Advanced) ​

For users with VPS, dedicated servers, or cloud hosting. This method provides full control and better performance.

Step 1: Server Preparation ​

  1. Connect to Your Server

    bash
    # Connect via SSH
ssh root@your-server-ip
# or
ssh username@your-server-ip

  2. Update System Packages

    bash
    # Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL/Rocky Linux
sudo yum update -y
# or for newer versions
sudo dnf update -y

  3. Install Required Software

    bash
    # Ubuntu/Debian
sudo apt install -y nginx mysql-server php8.2-fpm php8.2-mysql php8.2-curl php8.2-gd php8.2-mbstring php8.2-xml php8.2-zip php8.2-bcmath php8.2-tokenizer php8.2-dom php8.2-fileinfo php8.2-openssl php8.2-pcre composer git unzip curl

# CentOS/RHEL/Rocky Linux
sudo yum install -y nginx mysql-server php-fpm php-mysql php-curl php-gd php-mbstring php-xml php-zip php-bcmath php-tokenizer php-dom php-fileinfo php-openssl php-pcre composer git unzip curl

  4. Start and Enable Services

    bash
    sudo systemctl start nginx mysql php8.2-fpm
sudo systemctl enable nginx mysql php8.2-fpm

Step 2: Database Setup ​

  1. Secure MySQL Installation

    bash
    sudo mysql_secure_installation
    • Set root password when prompted
    • Remove anonymous users: Y
    • Disallow root login remotely: Y
    • Remove test database: Y
    • Reload privilege tables: Y

  2. Create Database and User

    bash
    sudo mysql -u root -p
    sql
    CREATE DATABASE helpdesk_pro CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'helpdesk_user'@'localhost' IDENTIFIED BY 'your_strong_password_here';
GRANT ALL PRIVILEGES ON helpdesk_pro.* TO 'helpdesk_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Download and Setup HelpDesk ​

  1. Navigate to Web Directory

    bash
    cd /var/www/html

  2. Download HelpDesk Pro

    bash
    # If you have the ZIP file, upload it first via SCP/SFTP, then:
unzip helpdesk-pro.zip
mv helpdesk-pro helpdesk
cd helpdesk

# Or if you have Git access:
# git clone https://github.com/your-repo/helpdesk-pro.git helpdesk
# cd helpdesk

  3. Install Dependencies

    bash
    # Install PHP dependencies
composer install --no-dev --optimize-autoloader

# Install Node.js dependencies (if Node.js is installed)
npm install
npm run build

  4. Set Proper Permissions

    bash
    sudo chown -R www-data:www-data /var/www/html/helpdesk
sudo chmod -R 755 /var/www/html/helpdesk
sudo chmod -R 777 /var/www/html/helpdesk/storage
sudo chmod -R 777 /var/www/html/helpdesk/bootstrap/cache

Step 4: Configure Nginx ​

  1. Create Nginx Configuration

    bash
    sudo nano /etc/nginx/sites-available/helpdesk

  2. Add Configuration

    nginx
    server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/html/helpdesk/public;
    
    index index.php index.html;
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header X-Content-Type-Options "nosniff" always;
    
    # Main location block
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    # PHP processing
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    # Deny access to hidden files
    location ~ /\.ht {
        deny all;
    }
    
    # Deny access to sensitive files
    location ~ /\.(env|git) {
        deny all;
    }
}

  3. Enable Site and Test

    bash
    sudo ln -s /etc/nginx/sites-available/helpdesk /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 5: Environment Configuration ​

  1. Create Environment File

    bash
    cd /var/www/html/helpdesk
cp .env.example .env

  2. Generate Application Key

    bash
    php artisan key:generate

  3. Configure Environment Variables

    bash
    nano .env

    Update these essential settings:

    bash
    APP_NAME="HelpDesk Pro"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=helpdesk_pro
DB_USERNAME=helpdesk_user
DB_PASSWORD=your_strong_password_here

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

Step 6: Run the Installation Wizard ​

  1. Access the Installer

    • Open your browser
    • Navigate to https://yourdomain.com/install
    • Follow the same installation wizard as the cPanel method

  2. Complete Installation

    • The installer will run database migrations
    • Create your admin account
    • Set up initial configuration

Step 7: Post-Installation (VPS) ​

  1. Optimize Performance

    bash
    cd /var/www/html/helpdesk
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan storage:link

  2. Set Up SSL (Recommended)

    bash
    # Install Certbot
sudo apt install certbot python3-certbot-nginx

# Get SSL certificate
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

# Test auto-renewal
sudo certbot renew --dry-run

  3. Configure Firewall

    bash
    sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

  4. Set Up Cron Jobs

    bash
    sudo crontab -e

    Add this line:

    bash
    * * * * * cd /var/www/html/helpdesk && php artisan schedule:run >> /dev/null 2>&1

Post-Installation Setup ​

1. Essential Configuration ​

  1. System Settings

    • Go to Admin → Settings → General
    • Set your company information
    • Configure timezone and language
    • Set up email templates

  2. Email Configuration

    • Go to Admin → Settings → Email
    • Configure SMTP settings
    • Test email delivery
    • Set up email notifications

  3. Departments Setup

    • Go to Admin → Departments
    • Create departments (Technical Support, Sales, Billing, etc.)
    • Assign department managers
    • Set up routing rules

  4. Categories Setup

    • Go to Admin → Categories
    • Create ticket categories and subcategories
    • Set up auto-assignment rules
    • Configure SLA settings

2. Optional Features ​

  1. AI Features

    • Go to Admin → Settings → AI
    • Enter your OpenAI API key
    • Enable AI-powered features
    • Configure AI responses

  2. Real-Time Chat

    • Go to Admin → Settings → Chat
    • Configure Pusher settings
    • Enable live chat features
    • Set up chat widgets

  3. Email Piping

    • Go to Admin → Settings → Email Piping
    • Configure IMAP settings
    • Set up automatic ticket creation
    • Test email processing

Configuration Guide ​

Environment Variables ​

Key environment variables you should configure:

bash
# Application
APP_NAME="HelpDesk Pro"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=helpdesk_pro
DB_USERNAME=helpdesk_user
DB_PASSWORD=your_password

# Mail
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls

# OpenAI (for AI features)
OPENAI_API_KEY=your-openai-api-key
OPENAI_ORGANIZATION=your-org-id

# Pusher (for real-time features)
PUSHER_APP_ID=your-pusher-app-id
PUSHER_APP_KEY=your-pusher-key
PUSHER_APP_SECRET=your-pusher-secret
PUSHER_APP_CLUSTER=us2

# Queue
QUEUE_CONNECTION=database

Web Server Configuration ​

Apache (.htaccess) ​

apache
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

Nginx ​

nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/html/helpdesk/public;
    
    index index.php;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Troubleshooting ​

Common Issues and Solutions ​

Permission Errors ​

bash
# Fix storage permissions
sudo chown -R www-data:www-data /var/www/html/helpdesk
sudo chmod -R 755 /var/www/html/helpdesk
sudo chmod -R 777 /var/www/html/helpdesk/storage
sudo chmod -R 777 /var/www/html/helpdesk/bootstrap/cache

Database Connection Issues ​

  • Verify database credentials in .env
  • Ensure MySQL service is running
  • Check firewall settings
  • Verify database exists and user has permissions

Email Not Working ​

  • Verify SMTP settings in admin panel
  • Check spam folders
  • Test with different email providers
  • Verify email server allows SMTP connections

500 Internal Server Error ​

bash
# Check logs
tail -f /var/log/nginx/error.log
tail -f /var/www/html/helpdesk/storage/logs/laravel.log

# Clear caches
cd /var/www/html/helpdesk
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

Real-Time Features Not Working ​

  • Verify Pusher configuration
  • Check WebSocket support
  • Review browser console for errors
  • Ensure firewall allows WebSocket connections

Getting Help ​

If you encounter issues:

  1. Check the Logs

    • Laravel logs: storage/logs/laravel.log
    • Nginx logs: /var/log/nginx/error.log
    • PHP logs: /var/log/php8.2-fpm.log

  2. Clear Caches

    bash
    php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

  3. Contact Support

    • Visit our support page
    • Provide detailed error information
    • Include relevant log files

Next Steps ​

Once installation is complete:

  1. Read the User Guide to learn how to use the system
  2. Configure AI Features for intelligent automation
  3. Set up Email Piping for automatic ticket creation
  4. Explore Customization Options to tailor the system to your needs

📹 Video Tutorials ​

Complete Installation Walkthrough ​

Watch this comprehensive video tutorial for a complete step-by-step installation process:

🎥 HelpDesk Pro Installation Tutorial

This video covers:

  • Downloading and extracting files
  • Uploading to cPanel
  • Creating database
  • Running the installation wizard
  • Post-installation setup

Additional Help Videos ​

📁 Creating Subdomain in cPanel:How to Create a Subdomain in cPanel

🗄️ Creating Database in cPanel:How to Create a MySQL Database in cPanel

🎉 Congratulations! ​

You've successfully installed HelpDesk Pro! Your AI-powered customer support system is now ready to help you deliver exceptional customer experiences.

📞 Need Help? ​

  • Documentation: Browse our comprehensive guides
  • Support: Contact our support team
  • Community: Join our user community for tips and tricks

Last updated: January 2025

Released under the MIT License.

Copyright © 2025 HelpDesk Pro