Skip to main content

Installation

This guide walks you through installing Open Core Business Suite on different hosting environments.

Don't have a license yet?

Purchase the application to get started:

Need help with installation? Buy Professional Installation

Choose Your Hosting Type​

Select the installation method based on your hosting environment:

Hosting TypeBest ForDifficulty
cPanel/Shared HostingSmall businesses, budget hostingEasy
VPS/Dedicated ServerFull control, scalabilityIntermediate
Cloud PlatformsAWS, DigitalOcean, etc.Advanced

cPanel / Shared Hosting​

This method works with most shared hosting providers like Bluehost, Hostinger, SiteGround, A2 Hosting, Namecheap, etc.

Prerequisites​

  • cPanel access to your hosting account
  • PHP 8.4+ (check with your host)
  • MySQL 8.0+ or MariaDB 10.6+
  • At least 512MB PHP memory limit
  • Composer installed or SSH access (for dependencies)

Step 1: Create Database​

  1. Log into your cPanel
  2. Navigate to MySQL Databases
  3. Create a new database (e.g., username_opencorebs)
  4. Create a new database user with a strong password
  5. Add the user to the database with All Privileges
  6. Note down the database name, username, and password

Step 2: Upload Files​

Option A: Using File Manager

  1. Download the release package from your purchase dashboard
  2. In cPanel, go to File Manager
  3. Navigate to public_html (or your subdomain folder)
  4. Click Upload and upload the ZIP file
  5. Right-click the ZIP file and select Extract
  6. Move all files from the extracted folder to your target directory

Option B: Using FTP

  1. Connect to your server using FTP (FileZilla, Cyberduck, etc.)
  2. Upload the extracted files to public_html or your desired directory
  3. Ensure all files including hidden files (.env.example, .htaccess) are uploaded
Document Root

The web server should point to the /public folder. If you cannot change the document root, see the Subdirectory Installation section below.

Step 3: Configure Environment​

  1. In File Manager, locate .env.example in your application root
  2. Right-click and select Rename, change it to .env
  3. Right-click .env and select Edit
  4. Update the following settings:
APP_NAME="Your Company Name"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=username_opencorebs
DB_USERNAME=username_dbuser
DB_PASSWORD=your_database_password
  1. Save the file

Step 4: Install Dependencies​

If you have SSH Access (Terminal in cPanel):

  1. In cPanel, go to Terminal (or use SSH)
  2. Navigate to your application directory:
cd ~/public_html
  1. Run composer:
composer install --ignore-platform-reqs

If you don't have SSH Access:

  1. Install dependencies locally on your computer first
  2. Upload the vendor folder via FTP
  3. Or contact your host to enable SSH/Terminal access

Step 5: Generate Keys​

Via SSH/Terminal:

php artisan key:generate
php artisan jwt:secret

Without SSH: Add these manually to your .env file:

  1. Generate a random 32-character string for APP_KEY (format: base64:XXXXXXXX...)
  2. Generate another random string for JWT_SECRET
  3. Use an online Laravel key generator if needed

Via SSH/Terminal:

php artisan storage:link

Without SSH:

  1. In File Manager, navigate to the public folder
  2. Create a new folder named storage
  3. Or manually create a symbolic link via your host's support

Step 7: Set Permissions​

  1. In File Manager, navigate to your application root
  2. Right-click the storage folder → Change Permissions → Set to 775
  3. Right-click the bootstrap/cache folder → Change Permissions → Set to 775
  4. Right-click the public folder → Change Permissions → Set to 775
  5. Right-click the Modules folder → Change Permissions → Set to 775
  6. Set the modules_statuses.json file → Change Permissions → Set to 666

Step 8: Build Frontend Assets​

Option A: Pre-built Assets (Easiest)

If your package includes pre-built assets in public/build/, skip this step.

Option B: Build on Server (SSH required)

First ensure Node.js 18+ is installed. You can install it via:

# Check if Node.js is installed
node -v

# If not installed, install via NodeSource (Ubuntu/Debian example):
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or on cPanel, check if Node.js is available via "Setup Node.js App" in cPanel

Then build the assets:

npm install
npm run build

Option C: Build Locally and Upload

  1. On your local machine with Node.js 18+ installed: 
    npm install
    npm run build
  2. Upload the public/build/ folder to your server

Step 9: Setup Database​

Via SSH/Terminal:

php artisan opencorebs:live --fresh

Without SSH (Using Web Installer):

  1. Navigate to https://yourdomain.com/install (if web installer is included)
  2. Follow the on-screen instructions

Manual Database Setup (Alternative):

  1. Import the SQL file (if provided) via phpMyAdmin in cPanel
  2. Or run migrations via a web-based artisan runner

Step 10: Configure .htaccess (if needed)​

If your site shows a directory listing or 404 errors, ensure .htaccess exists in the public folder with:

<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>

Subdirectory Installation​

If you cannot set the document root to /public and must install in a subdirectory:

  1. Copy the public/.htaccess to your application root
  2. Copy public/index.php to your application root
  3. Edit the root index.php and update paths:
// Change these lines:
require __DIR__.'/../vendor/autoload.php';
$app = require_once __DIR__.'/../bootstrap/app.php';

// To:
require __DIR__.'/vendor/autoload.php';
$app = require_once __DIR__.'/bootstrap/app.php';
  1. Update APP_URL in .env to include the subdirectory path
Security Note

Installing in the root directory exposes your application files. The recommended approach is always to point the document root to /public.

VPS / Dedicated Server​

For servers where you have full SSH access and control (Ubuntu, Debian, CentOS, etc.).

Prerequisites​

  • SSH access to your server
  • PHP 8.4+ with required extensions
  • MySQL 8.0+ or MariaDB 10.6+
  • Composer 2.x installed
  • Node.js 18+ and npm installed
  • Nginx or Apache web server

Step 1: Upload Files​

# Download and extract the package
cd /var/www
unzip opencorebs-v*.zip -d html/
cd html

Step 2: Install Dependencies​

composer install --ignore-platform-reqs

Step 3: Configure Environment​

cp .env.example .env
nano .env  # or vim .env

Update database and application settings. See Configuration Guide for details.

Step 4: Generate Security Keys​

php artisan key:generate
php artisan jwt:secret
php artisan storage:link

Step 6: Build Frontend Assets​

Standard Build (8GB+ RAM):

npm install
npm run build

Optimized Build (4-8GB RAM):

npm install
npm run build:server:optimized

Low Memory Servers (Create Swap First):

# Create 4GB swap file
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Then build
npm run build:server:optimized

Step 7: Setup Database​

For Production:

php artisan opencorebs:live --fresh

This interactive command prompts for admin credentials and sets up production data.

For Development/Testing:

php artisan opencorebs:demo --fresh

Demo credentials: [email protected] / password123

Step 8: Set Permissions​

# Set ownership (replace www-data with your web server user)
sudo chown -R www-data:www-data /var/www/html

# Set directory permissions
find /var/www/html -type d -exec chmod 755 {} \;

# Set file permissions
find /var/www/html -type f -exec chmod 644 {} \;

# Make storage and cache writable
chmod -R 775 storage bootstrap/cache

Step 9: Configure Web Server​

Nginx Configuration​

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/html/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Apache Configuration​

Ensure mod_rewrite is enabled:

sudo a2enmod rewrite
sudo systemctl restart apache2

Apache virtual host:

<VirtualHost *:80>
    ServerName yourdomain.com
    DocumentRoot /var/www/html/public

    <Directory /var/www/html/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/opencorebs_error.log
    CustomLog ${APACHE_LOG_DIR}/opencorebs_access.log combined
</VirtualHost>

For background jobs like sending emails:

# Using Supervisor (recommended for production)
sudo apt install supervisor

# Create config file
sudo nano /etc/supervisor/conf.d/opencorebs-worker.conf

Add:

[program:opencorebs-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/html/storage/logs/worker.log

Start the worker:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start opencorebs-worker:*

Cloud Platforms​

For cloud deployments on AWS, DigitalOcean, Google Cloud, Azure, etc.

DigitalOcean​

  1. Create a Droplet with Ubuntu 22.04+
  2. Use the LAMP or LEMP marketplace image
  3. Follow the VPS Installation steps above

AWS (EC2)​

  1. Launch an EC2 instance with Amazon Linux 2 or Ubuntu
  2. Install LAMP/LEMP stack
  3. Follow the VPS Installation steps

Laravel Forge / Ploi​

These services automate server management:

  1. Connect your server provider
  2. Create a new server and site
  3. Deploy your code via Git or upload
  4. Run post-deployment commands in the dashboard

Command Reference​

Setup Commands​

CommandDescription
php artisan opencorebs:live --freshProduction setup with interactive prompts
php artisan opencorebs:demo --freshDevelopment setup with demo data

Options​

OptionDescription
--freshDrop all tables and re-run migrations
--forceForce operation in production

Manual Seeding​

# Production (prompts for admin credentials)
php artisan db:seed --class=LiveSeeder

# Development (demo data)
php artisan db:seed --class=DemoSeeder

Verify Installation​

  1. Open your browser and navigate to your domain
  2. Log in with the admin credentials you created
  3. You should see the dashboard

Troubleshooting​

500 Internal Server Error​

# Check Laravel logs
tail -f storage/logs/laravel.log

# Check PHP error logs
tail -f /var/log/php-fpm/error.log  # VPS
# Or check error_log in cPanel

Blank White Page​

  1. Enable debug mode temporarily: Set APP_DEBUG=true in .env
  2. Check the error message
  3. Disable debug mode after fixing: Set APP_DEBUG=false

Permission Denied Errors​

chmod -R 775 storage bootstrap/cache

On cPanel: Right-click folders → Change Permissions → 775

Database Connection Errors​

  1. Verify .env database credentials
  2. Check database server is running
  3. Ensure database user has correct privileges
  4. On shared hosting, database host might be localhost or an IP

CSS/JS Not Loading​

  1. Run php artisan storage:link
  2. Check if public/build/ folder exists
  3. Clear browser cache
  4. Check .htaccess is present in public/

Artisan Commands Not Working (cPanel)​

  1. Use full PHP path: /usr/local/bin/php artisan ...
  2. Or set up a cron job to run commands
  3. Contact host to enable SSH access

External Service Setup​

Firebase (Required for Mobile Apps)​

Firebase is required for push notifications in the Employee App and Field Sales App.

  1. Create a project at Firebase Console
  2. Add an Android app with your package name
  3. Download google-services.json and place it in the app's android/app/ directory
  4. For iOS, download GoogleService-Info.plist and add to ios/Runner/
  5. Enable Cloud Messaging in Firebase Console

See the mobile app setup guides for detailed instructions:

Google Cloud / Maps API (Required for Location Features)​

Location-based features (field tracking, geofencing, site attendance, client maps) require a Google Maps API key.

  1. Create a project at Google Cloud Console
  2. Enable the following APIs:
    • Maps JavaScript API (for web maps)
    • Maps SDK for Android (for mobile apps)
    • Maps SDK for iOS (for iOS apps)
    • Geocoding API (for address lookup)
    • Places API (optional, for location search)
  3. Create an API key under Credentials
  4. In the admin panel, go to Settings > Map Settings and enter your API key, map provider, zoom level, and center coordinates
  5. For mobile apps, also add the key to:
    • Android: android/app/src/main/AndroidManifest.xml
    • iOS: ios/Runner/AppDelegate.swift
Restrict Your API Key

In Google Cloud Console, restrict your API key to specific APIs and HTTP referrers/app packages to prevent unauthorized usage.

Next Steps​

Last updated on