Server Configuration – XRemit Documentation

cPanel Deployment Guide

Deploy your Laravel application using cPanel's File Manager, MySQL Databases tool, and Terminal — the most widely available shared hosting control panel.

cPanel / WHMPHP 8.2Laravel 10.10MySQL 8.0Apache + mod_rewrite

Server Requirements

Ensure your cPanel hosting plan meets these specifications

PHP Version

8.2

Laravel

10.10

Database

MySQL 8.0

Web Server

Apache + mod_rewrite

Composer

Required

Terminal

Required

ℹ

Required PHP extensions: openssl, pdo, mbstring, tokenizer, json, gd, curl, zip, zlib, fileinfo, exif, bcmath. Ensure mod_rewrite is enabled in Apache.

Upload Project Files

Upload your project ZIP via cPanel File Manager

1
Log in to cPanel
Access cPanel at yourdomain.com/cpanel or :2083.
2
Open File Manager
In cPanel, go to the Files section → click File Manager.
3
Navigate to public_html
Click on public_html in the left directory tree.
4
Upload the ZIP File
Click Upload → drag and drop your [project-name]-web-[version].zip. Wait for progress bar to reach 100%.

💡

You can also upload via FTP/SFTP using FileZilla. Use port 21 for FTP or 22 for SFTP.

Extract Files

Extract the ZIP and set the correct document root

1
Right-click the ZIP File
Right-click on [project-name]-web-[version].zip → select Extract.
2
Set Extraction Path
Enter /public_html as destination → click Extract Files.
3
Set Document Root to /public
In cPanel, go to Domains → your domain → Document Root → set to /public_html/public → click Save.

⚠

If your host doesn't allow changing document root, move files from public into public_html and edit index.php paths accordingly.

🔧

After extraction you should see: app/, bootstrap/, config/, public/, routes/, storage/, and .env.example.

Create MySQL Database

Set up a database and user via cPanel MySQL Databases

1
Open MySQL Databases
In cPanel, go to Databases → MySQL® Databases.
2
Create New Database
Enter database name (e.g. myapp) → click Create Database. cPanel prefixes it (e.g. cpanelusername_myapp).
3
Add a MySQL User
Go to MySQL Users → Add New User. Enter username and strong password. Click Create User.
4
Add User to Database
In Add User To Database, select your user and database → click Add.
5
Grant All Privileges
On Manage User Privileges, check ALL PRIVILEGES → click Make Changes.

ℹ

Note down the full database name and full username (with cPanel prefix) for the .env file.

Configure .env File

Set up your application's environment configuration

1
Copy .env.example
In File Manager, find .env.example → Right-click → Copy → rename to .env.
2
Edit the .env File
Right-click .env → Edit. Update values below → click Save Changes.

.env — Key Configuration Values

APP_NAME="Your App Name"
APP_ENV=production
APP_KEY=   # Will be generated via artisan key:generate
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cpanelusername_myapp    # Full prefixed database name
DB_USERNAME=cpanelusername_script   # Full prefixed username
DB_PASSWORD=YourStrongPassword123!

MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=465
[email protected]
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=ssl

Run Composer & Artisan Commands

Install dependencies and initialize the application via Terminal

🖥

Open cPanel's built-in terminal: go to Advanced → Terminal. This gives you SSH-like access directly in the browser.

bash — Navigate to Project

cd ~/public_html

bash — Install Composer Dependencies

# If Composer is available globally:
composer install --no-dev --optimize-autoloader

# If Composer is not in PATH, download it first:
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php composer.phar install --no-dev --optimize-autoloader

bash — Laravel Setup Commands

# Generate application key
php artisan key:generate

# Run database migrations
php artisan migrate --force

# Create symbolic link for storage
php artisan storage:link

# Cache configuration and routes for performance
php artisan config:cache
php artisan route:cache
php artisan view:cache

bash — Fix File Permissions

chmod -R 755 ~/public_html
chmod -R 775 ~/public_html/storage
chmod -R 775 ~/public_html/bootstrap/cache

Apache & .htaccess Configuration

Ensure mod_rewrite is active and URL routing works correctly

ℹ

cPanel uses Apache with mod_rewrite by default. Laravel's public/.htaccess is already included and handles URL rewriting automatically.

.htaccess — public/.htaccess (Already Included)

# This file is included — verify it exists at 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>

🔒

To enable free SSL: go to Security → SSL/TLS Status → click Run AutoSSL.

⚠

If you get 500 Internal Server Error, check whether AllowOverride All is set. Contact your host if .htaccess rules are not being respected.

Final Steps

Set PHP version, enable extensions, and launch

1
Set PHP Version to 8.2
In cPanel, go to Software → Select PHP Version. Change to 8.2 → click Set as current.
2
Enable Required PHP Extensions
Enable: openssl, pdo, pdo_mysql, mbstring, tokenizer, json, gd, curl, zip, zlib, fileinfo, exif, bcmath → click Save.
3
Enable SSL Certificate
Go to Security → SSL/TLS Status → click Run AutoSSL.
4
Open Your Website
Navigate to https://yourdomain.com. The installation wizard will guide you.

✅

Installation complete! If the site doesn't load, verify document root is public_html/public, PHP is 8.2, and all extensions are enabled.

Common Issue	Solution
500 Internal Server Error	Check `storage/logs/laravel.log`; set `APP_DEBUG=true` temporarily
Database connection failed	Verify DB credentials include cPanel prefix (e.g. `cpanelusername_myapp`)
404 on all routes	Ensure document root is `public_html/public` and `mod_rewrite` is enabled
Blank white page	Run `php artisan config:clear` via Terminal; confirm PHP is 8.2
Composer not found	Download manually: `php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"`
Permission denied errors	Run `chmod -R 775 storage bootstrap/cache` from Terminal
Images/files not loading	Run `php artisan storage:link` to create the public storage symlink

Steps