Install FreeScout on cPanel — Complete Guide (2025)

Most cPanel hosting is shared hosting, which doesn't support FreeScout. But if you have a dedicated or VPS with cPanel (WHM), you can install FreeScout. This guide shows you how.

Why cPanel?

Pros:

• ✅ Familiar GUI (no SSH required)
• ✅ Easy database management
• ✅ Built-in SSL via AutoSSL
• ✅ File manager (no SFTP needed)
• ✅ One-click backup restore

Cons:

• ❌ Less control than command line
• ❌ cPanel adds overhead (uses more resources)
• ❌ Can't easily customize server stack
• ❌ More expensive than raw VPS

Best for: Non-technical users who prefer GUI, already have cPanel VPS.

Prerequisites

• NOT shared hosting (requires CLI access, Composer, etc.)
• Dedicated server or VPS with WHM (WebHost Manager) installed
• cPanel account on that WHM server
• PHP 8.2 available in WHM
• SSH access (for Composer installation)

Important: Contact your hosting provider to confirm they support custom applications like FreeScout.

Step 1: Create cPanel Account (WHM)

If you're the WHM root:

1. Log into WHM (usually port 2087)
2. Go to Account Functions → Create a New Account
3. Fill in domain and account details
4. Create account

If you already have a cPanel account, skip this.

Step 2: Select PHP Version

Via cPanel:

1. Log into cPanel
2. Go to Select PHP Version
3. Choose 8.2 (required for FreeScout)
4. Ensure these modules are enabled:
   • mysqli
   • mbstring
   • xml
   • curl
   • imap
   • zip
   • gd
   • intl

If you need more control, use WHM → EasyApache 4 to customize PHP modules.

Step 3: Create MySQL Database via cPanel

1. Log into cPanel
2. Go to Databases → MySQL Databases
3. Create new database: freescout
4. Create MySQL user: freescout_user
5. Set strong password
6. Grant all privileges to user on database
7. Note the credentials

Step 4: Create cPanel Addon Domain

1. Go to Addon Domains
2. Domain: freescout.your-domain.com (or your domain)
3. Document root: /public_html/freescout/public
4. Create domain

Step 5: Upload FreeScout Files

Via File Manager:

1. Go to File Manager
2. Navigate to /public_html/
3. Upload FreeScout files:
   • Download FreeScout ZIP: https://github.com/freescout-helpdesk/freescout/archive/refs/heads/main.zip
   • Upload via File Manager (or FTP)
   • Extract to /public_html/freescout/

Or via SSH (if your host allows):

cd /home/username/public_html
wget https://github.com/freescout-helpdesk/freescout/archive/refs/heads/main.zip
unzip main.zip
mv freescout-main freescout

Step 6: Install Composer (SSH Required)

SSH into your account:

cd /home/username/public_html/freescout
curl -sS https://getcomposer.org/installer | php
php composer.phar install --no-dev --optimize-autoloader

This installs PHP dependencies (takes 3–5 minutes).

Step 7: Set File Permissions

cd /home/username/public_html/freescout

# Web server owns FreeScout
chown -R nobody:nobody .

# Directories: 755, Files: 644
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;

# Special permissions for storage
chmod 777 storage bootstrap/cache

Step 8: Configure Environment

cd /home/username/public_html/freescout
cp .env.example .env
nano .env

Update:

APP_URL=https://freescout.your-domain.com
APP_KEY=   # Leave blank, auto-generated
DB_HOST=localhost
DB_DATABASE=freescout
DB_USERNAME=freescout_user
DB_PASSWORD=your_strong_password
MAIL_DRIVER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key

Step 9: Generate Keys & Migrate

php artisan key:generate
php artisan migrate --force
php artisan freescout:after-app-update
php artisan storage:link

Step 10: Configure .htaccess (cPanel's Apache)

Create /public_html/freescout/public/.htaccess:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} (.+)/$
    RewriteRule ^ %1 [L,R=301]

    # Send Requests To Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

Step 11: Enable AutoSSL (cPanel's Built-In SSL)

1. Go to cPanel → Domains
2. Find your FreeScout domain
3. Click "Manage AutoSSL"
4. Enable AutoSSL
5. Certificate auto-renews annually

Step 12: Configure Cron Jobs (cPanel)

FreeScout needs to run artisan schedule:run every minute.

1. Go to Cron Jobs
2. Create new cron:
   • Command: php /home/username/public_html/freescout/artisan schedule:run
   • Interval: Every minute (* * * * *)

Step 13: Queue Workers (Important)

Problem: cPanel doesn't have Supervisor (needed for queue workers).

Solution: Use cPanel Cron to emulate queue worker.

Create a cron job that runs every minute:

php /home/username/public_html/freescout/artisan queue:work database --sleep=3 --tries=1 --max-time=59

This processes one queue job per minute. Not ideal (slower email), but works on cPanel.

Better solution: Upgrade to VPS with WHM/Supervisor, or use a different host.

Step 14: Test Installation

1. Visit https://freescout.your-domain.com
2. Complete web installer
3. Create admin account
4. Configure first mailbox
5. Test email sending

cPanel Limitations

FreeScout on cPanel has issues:

1. Queue workers slow: Cron-based instead of Supervisor (slower email processing)
2. Limited customization: Can't easily modify server stack
3. Higher cost: cPanel hosting typically $20+/month (vs $6/month for raw VPS)
4. Less efficient: cPanel adds overhead

Real talk: FreeScout on cPanel works, but it's not optimal. A raw VPS is cheaper and better for FreeScout.

cPanel vs Raw VPS

| | cPanel | Raw VPS | |---|---|---| | Cost | $20–$40/month | $6–$12/month | | Ease of use | Very easy (GUI) | Requires SSH knowledge | | Queue workers | Slow (cron-based) | Fast (Supervisor) | | Customization | Limited | Full | | SSL | Auto (AutoSSL) | Manual (Let's Encrypt) | | Backups | Built-in | Your responsibility | | Best for | Non-technical users | Technical teams |

If you're comfortable with SSH, raw VPS is better for FreeScout. If you're not technical, cPanel is acceptable (just slower email).

Troubleshooting

| Issue | Cause | Fix | |---|---|---| | "PHP Composer not found" | Composer not installed | SSH in and install: curl -sS https://getcomposer.org/installer | php | | "404 Not Found" | .htaccess not working | Check mod_rewrite is enabled in WHM | | "Cannot write to storage/" | Wrong permissions | Set storage permissions to 777: chmod 777 storage bootstrap/cache | | "Emails not sending" | Queue worker too slow | Upgrade to VPS with Supervisor |

When to Use cPanel for FreeScout

✅ Use cPanel if:

• You prefer GUI over command line
• You're not technical
• You're already paying for cPanel
• You have low email volume (slow queue workers acceptable)

❌ Don't use cPanel if:

• You need fast email processing
• You care about cost
• You're technical (raw VPS is better)
• You have high-volume support (100+ emails/day)

Recommendation

Start with a raw VPS (DigitalOcean, Hetzner, Linode, Vultr). It's:

• Cheaper ($6–$12/month vs $20–$40/month)
• Faster (native queue workers vs cron)
• More flexible (full control)
• Better for FreeScout

If you need GUI, use Docker (easier than cPanel) or DigitalOcean App Platform (managed).

cPanel works for FreeScout, but it's not the optimal choice.

Summary

FreeScout can run on cPanel, but it's the least ideal deployment option. cPanel adds cost, complexity, and performance limitations.

If you're already on cPanel, yes, you can install FreeScout. But if you're choosing a platform, pick VPS or App Platform instead.

Resources

• cPanel Documentation — official cPanel guide
• FreeScout GitHub — source code and releases
• Composer Download — PHP dependency manager
• cPanel PHP Configuration — PHP settings guide