Appearance

Installation on cPanel ​

This guide will walk you through installing Growstack CRM on a cPanel hosting account.

Refer to the online documentation for video tutorials covering the cPanel installation process.

Table of Contents ​

  1. Prerequisites
  2. Step 1: Create Database
  3. Step 2: Set Up Domain or Subdomain
  4. Step 3: Upload Files
  5. Step 4: Set File Permissions
  6. Step 5: Run the Installer
  7. Step 6: Post-Installation
  8. 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., crm.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., growstack_crm)
  4. Click Create Database
  5. Note the full database name (usually username_growstack_crm)

1.2 Create Database User ​

  1. Scroll down to MySQL Users section
  2. Enter a username (e.g., growstack_crm_user)
  3. Enter a strong password (use the password generator)
  4. Click Create User
  5. Note the full username (usually username_growstack_crm_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_growstack_crm
  • Database User: username_growstack_crm_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., crm.yourdomain.com)

Subdirectory Issues:

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

2.2 Create Subdomain (Recommended) ​

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

Example:

  • Subdomain: crm.yourdomain.com
  • Document Root: public_html/crm/
  • Full URL: https://crm.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 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/crm/ (e.g., for crm.yourdomain.com)
    • Main domain: public_html/
  3. Delete the default index.html if it exists
  4. Click Upload button
  5. Select the Growstack CRM package ZIP file
  6. Upload the file (this may take several minutes)
  7. Extract the ZIP file:
    • 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 Growstack CRM package
  5. Ensure all files are uploaded (maintain directory structure)

Important Files to Verify:

  • .env.example file exists
  • composer.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/crm
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: https://crm.yourdomain.com/install
    • Main domain: https://yourdomain.com/install
  3. You should see the Growstack CRM 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 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

Step 3: Environment Configuration ​

  • App Name: Enter your company or application name
  • App URL: Enter your full URL (e.g., https://crm.yourdomain.com)
    • Include the protocol (https://)
    • No trailing slash
  • Environment: Select production for live sites
  • Click Next to continue

Step 4: Database Configuration ​

Enter your database credentials (from Step 1):

  • Database Connection: Select mysql
  • Database Host: Usually localhost
  • Database Port: 3306
  • Database Name: username_growstack_crm
  • Database Username: username_growstack_crm_user
  • 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: https://crm.yourdomain.com/login
  • 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 at /admin
  2. Configure Settings:
    • Go to Settings → General
    • Update app 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
  5. Review Module Settings:
    • Go to Settings → Module Settings
    • Enable or disable optional modules

6.3 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/crm/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.4 Set Up Queue Worker ​

Growstack CRM uses queues for email sending and background jobs. Set up a queue worker:

  1. In cPanel, go to Cron Jobs
  2. Add (adjust path for your installation):
bash
php /home/username/public_html/crm/artisan queue:work --stop-when-empty

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

For production, using Supervisor on a VPS is recommended for a persistent queue worker.

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 (e.g., https://crm.yourdomain.com/install)

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. Use the full database name as shown in cPanel (e.g., username_growstack_crm)

Issue: Permission Denied Errors ​

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

Solutions:

  1. Set correct permissions (see Step 4)
  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, gd, bcmath
  4. Save changes

Security Recommendations ​

After installation:

  1. Set proper file permissions (directories: 755, files: 644)
  2. Enable SSL/HTTPS (use Let's Encrypt in cPanel)
  3. Set a strong admin password
  4. Regular backups (use cPanel Backup tool)
  5. Keep Growstack CRM 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

Released under the MIT License.

Copyright © 2026 Growstack CRM