Installation

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

Choose Your Hosting Type

Select the installation method based on your hosting environment:

Hosting Type	Best For	Difficulty
cPanel/Shared Hosting	Small businesses, budget hosting	Easy
VPS/Dedicated Server	Full control, scalability	Intermediate
Cloud Platforms	AWS, 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.2+ (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

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

3. Run composer:

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

Step 6: Create Storage Link

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

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)

npm install
npm run build

Option C: Build Locally and Upload

1. On your local machine with Node.js 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';

4. 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.2+ 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 update --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

Step 5: Create Storage Link

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

Step 10: Setup Queue Worker (Optional but Recommended)

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

Command	Description
php artisan opencorebs:live --fresh	Production setup with interactive prompts
php artisan opencorebs:demo --fresh	Development setup with demo data

Options

Option	Description
--fresh	Drop all tables and re-run migrations
--force	Force 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

---

Next Steps

• Configure environment settings
• Complete first login setup
• Enable additional modules