Appearance

Installation on cPanel ​

This guide will walk you through installing OmniSuite CMS on a cPanel hosting account.

🎥 Quick Installation Video ​

Watch this step-by-step video to see the complete installation process on cPanel shared hosting in just a few minutes:

📖 Prefer written instructions? Continue reading below for detailed step-by-step guidance with troubleshooting tips.

Table of Contents ​

  1. Prerequisites
  2. Step 1: Create Database
  3. Step 2: Upload Files
  4. Step 3: Set File Permissions
  5. Step 4: Run the Installer
  6. Step 5: Post-Installation
  7. Troubleshooting

Prerequisites ​

Before starting, ensure you have:

  • ✅ cPanel hosting account with PHP 8.2+ support
  • ✅ Database creation privileges
  • ✅ FTP or File Manager access
  • ✅ Domain configured (subdomain recommended)
  • ✅ Reviewed System Requirements

Important: For best results with Laravel applications, we recommend installing on a subdomain (e.g., app.yourdomain.com) rather than in a subdirectory. This ensures proper routing, asset loading, and avoids conflicts with other applications.

Step 1: Create Database ​

1.1 Create MySQL Database ​

  1. Log in to your cPanel account
  2. Navigate to MySQL Databases (under "Databases" section)
  3. In the "Create New Database" field, enter a database name (e.g., omnisuite_db)
  4. Click Create Database
  5. Note the full database name (usually username_omnisuite_db)

1.2 Create Database User ​

  1. Scroll down to MySQL Users section
  2. Enter a username (e.g., omnisuite_user)
  3. Enter a strong password (use the password generator)
  4. Click Create User
  5. Note the full username (usually username_omnisuite_user)

1.3 Assign User to Database ​

  1. Scroll to Add User to Database section
  2. Select the user you created
  3. Select the database you created
  4. Click Add
  5. Check ALL PRIVILEGES
  6. Click Make Changes

Important: Save these credentials:

  • Database Name: username_omnisuite_db
  • Database User: username_omnisuite_user
  • Database Password: your_password
  • Database Host: Usually localhost (check with your host)

Step 2: Set Up Domain or Subdomain ​

2.1 Why Subdomain is Recommended ​

Laravel Best Practice: Laravel applications are designed to run on their own domain or subdomain, not in subdirectories. Here's why:

✅ Proper Routing: Laravel's routing system works correctly without path conflicts
✅ Asset Loading: CSS, JavaScript, and images load from the correct paths
✅ Session Management: Cookies and sessions work properly
✅ Security: Better isolation and security configuration
✅ Performance: No conflicts with other applications
✅ URL Structure: Clean, professional URLs (e.g., app.yourdomain.com)

Subdirectory Issues:

  • ❌ Routing conflicts with other applications
  • ❌ Asset paths may break
  • ❌ Session/cookie domain issues
  • ❌ Complex .htaccess configuration needed
  • ❌ Potential conflicts with existing files

2.2 Create Subdomain (Recommended) ​

  1. In cPanel, navigate to Subdomains (under "Domains" section)
  2. Enter your subdomain name:
    • Common choices: app, cms, admin, dashboard, portal
    • Example: app → creates app.yourdomain.com
  3. Select your main domain from the dropdown
  4. The document root will auto-populate (e.g., public_html/app)
  5. Click Create
  6. Wait for confirmation message
  7. Note the document root path (you'll need this for file upload)

Example:

  • Subdomain: app.yourdomain.com
  • Document Root: public_html/app/
  • Full URL: https://app.yourdomain.com

2.3 Using Main Domain ​

If you prefer to use your main domain:

  • Document Root: public_html/
  • Full URL: https://yourdomain.com
  • Important: This will replace your main website. Consider using a subdomain instead to keep your main site separate.

Step 3: Upload Files ​

You have two options for uploading files:

  1. In cPanel, open File Manager
  2. Navigate to your installation directory:
    • Subdomain: public_html/subdomain_name/ (e.g., public_html/app/)
    • Main domain: public_html/
  3. Delete the default index.html if it exists
  4. Click Upload button
  5. Select all files from the OmniSuite CMS package
  6. Upload the files (this may take several minutes)
  7. Extract the ZIP file if you uploaded a compressed package:
    • Right-click the ZIP file
    • Select Extract
    • Delete the ZIP file after extraction

Option B: Using FTP ​

  1. Use an FTP client (FileZilla, WinSCP, etc.)
  2. Connect to your server:
    • Host: ftp.yourdomain.com or your server IP
    • Username: Your cPanel username
    • Password: Your cPanel password
    • Port: 21 (or 22 for SFTP)
  3. Navigate to your domain's root directory
  4. Upload all files from the OmniSuite CMS package
  5. Ensure all files are uploaded (maintain directory structure)

Important Files to Verify:

  • .env.example file exists
  • composer.json exists
  • package.json exists
  • artisan file exists
  • public/ directory exists

Step 4: Set File Permissions ​

4.1 Using File Manager ​

  1. In File Manager, navigate to your installation directory
  2. Set the following permissions:

Directories (755):

  • storage/
  • storage/framework/
  • storage/logs/
  • bootstrap/cache/
  • public/

Files:

  • .env (if exists): 644
  • artisan: 755

How to set permissions:

  1. Right-click the file/folder
  2. Select Change Permissions
  3. Enter the permission value (e.g., 755)
  4. Check Recurse into subdirectories for folders
  5. Click Change Permissions

4.2 Using Terminal (if available) ​

If you have SSH access:

bash
cd /home/username/public_html
chmod -R 755 storage bootstrap/cache
chmod -R 755 public
chmod 644 .env
chmod 755 artisan

Step 5: Run the Installer ​

5.1 Access the Installer ​

  1. Open your web browser
  2. Navigate to your installation URL:
    • Subdomain: http://app.yourdomain.com/install (replace app with your subdomain)
    • Main domain: http://yourdomain.com/install
  3. You should see the OmniSuite CMS installer welcome page

If you see a 404 error:

  • Check that files are in the correct directory
  • Verify .htaccess file exists in the public/ directory
  • Check if mod_rewrite is enabled

5.2 Installer Steps ​

Follow the installer wizard step by step:

Step 1: Welcome & Requirements ​

  • The installer automatically checks:
    • PHP version (must be 8.2.0+)
    • Required PHP extensions
    • Directory permissions
    • Server configuration
  • All checks should show green checkmarks
  • If any check fails, fix the issue before proceeding
  • Click Next to continue

Step 2: License Verification ​

  • Enter your CodeCanyon purchase code
  • Click Verify License
  • Wait for verification (requires internet connection)
  • ✅ Green checkmark = verified, proceed to next step
  • ❌ Red error = check purchase code and try again
  • Note: License verification is required to proceed

Step 3: Environment Configuration ​

  • App Name: Enter your site/application name
  • App URL: Enter your full URL:
    • Subdomain: https://app.yourdomain.com (no trailing slash)
    • Main domain: https://yourdomain.com (no trailing slash)
  • Environment: Select production for live sites
  • Mail Configuration (Optional): You can configure email now or later
  • Click Next to continue

Step 4: Database Configuration ​

Enter your database credentials (from Step 1):

  • Database Connection: Select mysql
  • Database Host: Usually localhost (check with your host if different)
  • Database Port: 3306 (default, usually doesn't need changing)
  • Database Name: username_omnisuite_db (full name from Step 1.1)
  • Database Username: username_omnisuite_user (full username from Step 1.2)
  • Database Password: The password you set in Step 1.2
  • Click Test Connection to verify credentials
  • ✅ Green checkmark = connection successful
  • ❌ Red error = check credentials and try again
  • Click Next if connection is successful

Step 5: Admin Account Setup ​

Create your first administrator account:

  • First Name: Your first name
  • Last Name: Your last name
  • Email: Your email address (use a valid email you can access)
  • Password: Strong password (minimum 8 characters, recommended 12+)
  • Confirm Password: Re-enter password exactly
  • ⚠️ Important: Save these credentials securely
  • Click Next to start installation

Step 6: Installation Progress ​

The installer will automatically:

  1. Save environment configuration (creates .env file)
  2. Run database migrations (creates all tables)
  3. Seed initial data (adds default settings and content)
  4. Create admin user (adds your administrator account)
  5. Finalize installation (marks app as installed)

Important:

  • ⚠️ Do not close the browser during this process
  • ⚠️ Do not refresh the page during installation
  • ⚠️ Installation typically takes 2-5 minutes
  • Wait for "Installation Complete" message

Step 7: Completion ​

  • You'll see a success message: "Installation Complete!"
  • Click Go to Login button
  • Or visit: http://app.yourdomain.com/login (or your domain)
  • Log in with your admin credentials from Step 5

Step 6: Post-Installation ​

6.1 Remove Installer Access ​

For security, the installer is automatically disabled after installation. If you need to reinstall:

  1. Delete or rename the .installed file in the root directory
  2. Or set APP_INSTALLED=false in .env file

6.2 Initial Configuration ​

  1. Log in to the admin panel
  2. Configure Settings:
    • Go to Admin Panel → Settings → General
    • Update site name, logo, and contact information
  3. Set up Email:
    • Go to Settings → Email Settings
    • Configure SMTP settings
  4. Configure Payment Gateways (if needed):
    • Go to Settings → Payment Gateways
    • Add your payment gateway credentials

6.3 Build Frontend Assets (if needed) ​

If you see unstyled pages:

  1. Access your server via SSH or Terminal in cPanel
  2. Navigate to your installation directory:
    bash
    # For subdomain
cd ~/public_html/app
# OR for main domain
cd ~/public_html
  3. Install dependencies and build assets:
    bash
    composer install --no-dev --optimize-autoloader
npm install
npm run build

6.4 Set Up Cron Jobs ​

  1. In cPanel, go to Cron Jobs
  2. Add the following cron job:

Command (adjust path for your installation):

bash
# For subdomain
php /home/username/public_html/app/artisan schedule:run >> /dev/null 2>&1
# OR for main domain
php /home/username/public_html/artisan schedule:run >> /dev/null 2>&1

Schedule: Every minute (* * * * *)

6.5 Set Up Queue Worker (if using queues) ​

If your application uses queues, set up a queue worker:

  1. In cPanel, go to Cron Jobs
  2. Add (adjust path for your installation):
bash
# For subdomain
php /home/username/public_html/app/artisan queue:work --daemon
# OR for main domain
php /home/username/public_html/artisan queue:work --daemon

Schedule: Every 5 minutes (*/5 * * * *)

Troubleshooting ​

Issue: Installer Not Loading ​

Symptoms: 404 error or blank page

Solutions:

  1. Check that files are in the correct directory
  2. Verify .htaccess file exists in public/ directory
  3. Check if mod_rewrite is enabled in cPanel
  4. Verify you're accessing the correct URL:
    • Subdomain: http://app.yourdomain.com/install
    • Main domain: http://yourdomain.com/install
  5. Try accessing: http://yourdomain.com/public/index.php (not recommended for production)

Issue: Database Connection Failed ​

Symptoms: "Database connection failed" error

Solutions:

  1. Verify database credentials are correct
  2. Check database host (may not be localhost - check with your host)
  3. Ensure database user has ALL PRIVILEGES
  4. Test connection using phpMyAdmin
  5. Check if database server is running

Issue: Permission Denied Errors ​

Symptoms: "Permission denied" or "Cannot write to directory"

Solutions:

  1. Set correct permissions (see Step 3)
  2. Ensure directories are writable (755 for directories)
  3. Check file ownership (should match cPanel user)
  4. Use File Manager to verify permissions

Issue: PHP Version Error ​

Symptoms: "PHP version 8.2.0 or higher required"

Solutions:

  1. In cPanel, go to Select PHP Version
  2. Choose PHP 8.2 or higher
  3. Click Set as current
  4. Refresh the installer page

Issue: Missing PHP Extensions ​

Symptoms: Extension check fails

Solutions:

  1. In cPanel, go to Select PHP Version
  2. Click Extensions
  3. Enable required extensions:
    • mbstring
    • xml
    • curl
    • intl
    • zip
    • pdo_mysql
  4. Save changes

Issue: Installation Stuck or Slow ​

Symptoms: Installer hangs on "Installation Progress"

Solutions:

  1. Check PHP execution time limit (should be 300+ seconds)
  2. Verify sufficient server resources
  3. Check error logs in cPanel
  4. Try increasing PHP memory limit
  5. Contact your hosting provider if issue persists

Issue: White Screen After Installation ​

Symptoms: Blank page after clicking "Go to Login"

Solutions:

  1. Check error logs in cPanel → Errors
  2. Verify .env file exists and is readable
  3. Check file permissions
  4. Clear browser cache
  5. Try accessing: http://yourdomain.com/login directly

Security Recommendations ​

After installation:

  1. Delete installer files (if you want to prevent reinstallation)
  2. Set proper file permissions (directories: 755, files: 644)
  3. Enable SSL/HTTPS (use Let's Encrypt in cPanel)
  4. Change default admin password immediately
  5. Regular backups (use cPanel Backup tool)
  6. Keep software updated

Next Steps ​

After successful installation:

  1. Review Post-Installation Setup
  2. Configure General Settings
  3. Set up Email Settings
  4. Read the Getting Started Guide

Support ​

If you need help:

  1. Check the Troubleshooting Guide
  2. Review cPanel error logs
  3. Contact your hosting provider
  4. Refer to application support channels

Last Updated: [Date will be updated during final review]

Released under the MIT License.

Copyright © 2024 OmniSuite CMS