Appearance

Web Installer Guide ​

Growstack CRM includes a built-in web installer that automates the installation process. This guide walks you through using the installer step by step.

Refer to the online documentation for video tutorials covering the web installer.

Table of Contents ​

  1. Accessing the Installer
  2. Step 1: Welcome & Requirements
  3. Step 2: Environment Configuration
  4. Step 3: Database Configuration
  5. Step 4: Admin Account Setup
  6. Step 5: Installation Progress
  7. Step 6: Completion
  8. Troubleshooting

Accessing the Installer ​

Prerequisites ​

Before accessing the installer, ensure:

  1. ✅ Files are uploaded to your server
  2. ✅ File permissions are set correctly (755 for directories, 644 for files)
  3. ✅ Database is created and credentials are ready
  4. ✅ Domain or subdomain is configured
  5. ✅ Server meets System Requirements

Important: For cPanel installations, we strongly recommend using a subdomain (e.g., crm.yourdomain.com) rather than installing in a subdirectory. This follows Laravel best practices and ensures proper routing and asset loading.

Access URL ​

Navigate to your domain or subdomain in a web browser:

For Main Domain:

https://yourdomain.com/install

For Subdomain (Recommended for cPanel):

https://crm.yourdomain.com/install

Important: Laravel applications work best when installed on a main domain or subdomain. Avoid installing in subdirectories as it can cause routing and asset loading issues.

First Time Access ​

On first access, you'll see the Welcome screen. The installer will automatically check your server requirements.

Step 1: Welcome & Requirements ​

What This Step Does ​

The installer automatically checks:

  • PHP version (must be 8.2.0+)
  • Required PHP extensions
  • Directory permissions
  • Server configuration

Requirements Check ​

You'll see a checklist with the following items:

PHP Version ​

  • ✅ Required: PHP 8.2.0 or higher
  • Shows your current PHP version
  • Must show green checkmark to proceed

PHP Extensions ​

Checks for required extensions:

  • ✅ OpenSSL
  • ✅ PDO
  • ✅ Mbstring
  • ✅ Tokenizer
  • ✅ XML
  • ✅ Ctype
  • ✅ JSON
  • ✅ cURL
  • ✅ Intl
  • ✅ GD
  • ✅ BCMath
  • ✅ Zip

Directory Permissions ​

Checks if these directories are writable:

  • ✅ storage/ directory
  • ✅ bootstrap/cache/ directory

If Requirements Fail ​

PHP Version Too Old:

  • Contact your hosting provider to upgrade PHP to 8.2 or higher
  • Or use cPanel "Select PHP Version" to choose PHP 8.2+

Missing Extensions:

  • Install missing extensions via your hosting control panel
  • In cPanel: Go to "Select PHP Version" → "Extensions" → Enable required extensions

Permission Issues:

  • Set directory permissions to 755 for directories, 644 for files
  • Ensure storage/ and bootstrap/cache/ are writable

Proceeding ​

Once all requirements show green checkmarks:

  1. Click Next or Continue button
  2. You'll proceed to License Verification

Step 2: Environment Configuration ​

App Information ​

App Name ​

  • Enter your company or application name
  • This will be used throughout the application
  • You can change this later in Settings
  • Example: Acme Corp CRM

App URL ​

  • Enter your full domain or subdomain URL
  • Important:
    • ✅ Include https:// or http:// protocol
    • ✅ Use subdomain format (recommended): https://crm.yourdomain.com
    • ✅ Use main domain format: https://yourdomain.com
    • ❌ Do not include trailing slash
    • ❌ Do not use subdirectory paths (e.g., /crm, /app)

Correct Examples:

  • ✅ https://crm.yourdomain.com (subdomain — recommended)
  • ✅ https://yourdomain.com (main domain)

Incorrect Examples:

  • ❌ yourdomain.com (missing protocol)
  • ❌ https://yourdomain.com/ (trailing slash)
  • ❌ https://yourdomain.com/crm (subdirectory — not supported)

Environment ​

Select your environment:

  • Production: For live installations (recommended)
  • Local: For local development

Mail Configuration (Optional) ​

You can configure email settings now or later in Settings → Email Settings.

Mail Driver ​

  • SMTP: For most hosting providers (recommended)
  • Sendmail: For servers with sendmail configured

SMTP Settings (if using SMTP) ​

  • Host: SMTP server address (e.g., smtp.gmail.com)
  • Port: SMTP port (usually 587 for TLS)
  • Username: Your email address
  • Password: Your email password or App Password
  • Encryption: TLS or SSL

Proceeding ​

  1. Fill in required fields (App Name, App URL)
  2. Optionally configure mail settings
  3. Click Next to continue

Step 3: Database Configuration ​

Database Connection Type ​

Select your database type:

  • MySQL: Most common (recommended)
  • PostgreSQL: Alternative database

MySQL Configuration ​

Enter your database credentials:

Database Host ​

  • Usually: localhost
  • Some hosts use: 127.0.0.1
  • Check with your hosting provider if unsure

Database Port ​

  • Default: 3306

Database Name ​

  • The database you created earlier
  • Example: growstack_crm or username_growstack_crm (full name on cPanel)

Database Username ​

  • The database user you created
  • Example: growstack_crm_user or username_growstack_crm_user (full name on cPanel)

Database Password ​

  • The password you set for the database user

Test Connection ​

  1. Click Test Connection button
  2. Wait for connection test result
  3. Success: Green checkmark — proceed to next step
  4. Failure: Red error message — check credentials

Common Connection Issues ​

"Access denied for user":

  • Verify username and password are correct
  • In cPanel: Check if user has ALL PRIVILEGES on the database
  • Ensure you're using the full username (e.g., cpanelusername_growstack_crm_user)

"Unknown database":

  • Verify database name is correct
  • In cPanel: Use the full database name including cPanel username prefix

"Can't connect to MySQL server":

  • Check database host (try 127.0.0.1 instead of localhost)
  • Verify database server is running

Proceeding ​

Once connection test succeeds:

  1. Click Next to continue
  2. You'll proceed to Admin Account Setup

Step 4: Admin Account Setup ​

Administrator Information ​

Create your first administrator account:

First Name / Last Name ​

  • Your name as admin user

Email Address ​

  • Your email address
  • Important: Use a valid email you can access
  • This will be used for login and password resets

Password ​

  • Minimum: 8 characters
  • Recommended: 12+ characters with a mix of uppercase, lowercase, numbers, and special characters

Confirm Password ​

  • Re-enter your password exactly

Security Notes ​

  • ⚠️ Save your credentials in a secure location
  • ⚠️ This account has full administrative access
  • ⚠️ Use a strong, unique password

Proceeding ​

  1. Fill in all required fields
  2. Ensure passwords match
  3. Click Next to start installation

Step 5: Installation Progress ​

What Happens During Installation ​

The installer will automatically:

  1. Save Configuration — Creates .env file with your settings
  2. Run Database Migrations — Creates all required database tables (1–2 minutes)
  3. Seed Initial Data — Creates default settings, CRM pipelines, lead sources, roles, and module settings
  4. Create Admin User — Adds your administrator account
  5. Finalize Installation — Marks application as installed

Progress Indicators ​

You'll see progress updates for:

  • ✅ Configuration saved
  • ✅ Database migrations completed
  • ✅ Database seeded
  • ✅ Admin user created
  • ✅ Installation complete

Important Notes ​

  • ⚠️ Do not close the browser during installation
  • ⚠️ Do not refresh the page during installation
  • ⚠️ Installation typically takes 2–5 minutes

If Installation Fails ​

Common causes:

  • Database connection lost
  • Insufficient file permissions
  • PHP timeout
  • Memory limit exceeded

Solutions:

  1. Read the error message details
  2. Verify database is still accessible
  3. Check file permissions
  4. Increase PHP memory limit to 256MB+
  5. Increase PHP execution time to 300 seconds

Step 6: Completion ​

Success Message ​

Upon successful installation, you'll see:

  • ✅ Installation Complete! message
  • Link to login page

Next Steps ​

  1. Click "Go to Login" button

    • Or visit: https://yourdomain.com/login

  2. Log in with your admin credentials

  3. First Login:

    • You'll be redirected to the CRM Dashboard (/admin/crm)
    • Complete initial setup:
      • Configure general settings
      • Set up email (if not done during installation)
      • Configure payment gateways (if needed)
      • Review module settings

Installer Lock ​

After installation:

  • The installer is automatically locked
  • You cannot re-run the installer without deleting the .installed file or setting APP_INSTALLED=false in .env

Troubleshooting ​

Installer Won't Load ​

Symptoms: 404 error or blank page

Solutions:

  1. Verify files are uploaded correctly to the server
  2. Check .htaccess file exists in the public/ directory
  3. Verify mod_rewrite is enabled (Apache)
  4. Try: http://yourdomain.com/public/index.php — if this works, .htaccess rewriting is the issue

Requirements Check Fails ​

Solutions:

  1. Upgrade PHP to 8.2+
  2. Install missing PHP extensions
  3. Fix directory permissions (755 for directories)
  4. Contact hosting provider if issues persist

Database Connection Fails ​

Solutions:

  1. Double-check all credentials (copy-paste, avoid typos)
  2. Verify database exists in phpMyAdmin
  3. Check user has ALL PRIVILEGES
  4. Verify database host (may not be localhost)

Installation Hangs or Fails ​

Solutions:

  1. Check PHP execution time (should be 300+ seconds)
  2. Increase PHP memory limit (256MB+)
  3. Check server error logs
  4. Verify sufficient disk space

Manual Installation Alternative ​

If the web installer doesn't work, you can install manually:

bash
cd /var/www/growstack-crm
cp .env.example .env
nano .env  # Configure DB_*, APP_URL, APP_KEY
php artisan key:generate
php artisan migrate --force
php artisan db:seed --force
php artisan storage:link

See VPS Installation Guide for detailed manual installation steps.

Next Steps ​

After successful installation:

  1. Review Post-Installation Setup
  2. Configure General Settings
  3. Read Getting Started Guide

Released under the MIT License.

Copyright © 2026 Growstack CRM