Skip to main content

Upgrade Guide

This guide covers how to update Open Core Business Suite to a new version. Since this is a source-code product, upgrades involve replacing application files with the new release and running a few commands to apply database changes.

Backup First

Always create a full backup of your database and files before upgrading. See Step 1 below.

Upgrade Overview​

Upgrading consists of four main steps:

  1. Back up your database and files
  2. Replace application files with the new release
  3. Run database migrations and clear caches
  4. Verify the upgrade

Step 1: Backup Your System​

Database Backup​

Via command line (SSH):

mysqldump -u your_db_user -p your_database_name > backup_$(date +%Y%m%d_%H%M%S).sql

Via cPanel:

  1. Open phpMyAdmin from cPanel
  2. Select your database
  3. Click Export and choose Quick export method
  4. Click Go to download the SQL file

Via System Backup Module:

If you have the System Backup module enabled:

  1. Navigate to System Backup in the admin panel
  2. Create a new backup that includes the database
  3. Download the backup file to your local machine

File Backup​

Back up your entire application directory:

# VPS / Dedicated Server
cd /var/www
tar -czf html_backup_$(date +%Y%m%d).tar.gz html/

Via cPanel:

  1. Open File Manager
  2. Navigate to your application directory
  3. Select all files and click Compress
  4. Download the resulting archive

Critical Files to Preserve​

Before replacing files, save copies of these files separately -- they contain your custom configuration:

FilePurpose
.envEnvironment configuration (database credentials, keys, etc.)
modules_statuses.jsonWhich modules are enabled/disabled
storage/Uploaded files, logs, and cached data
public/storageSymbolic link to storage (may need recreation)

Step 2: Replace Application Files​

Download the New Release​

Download the latest release package from your purchase dashboard on czappstudio.com.

Replace Files​

VPS / Dedicated Server (SSH):

cd /var/www

# Extract the new release to a temporary directory
unzip opencorebs-v*.zip -d html_new/

# Preserve your environment file
cp html/.env html_new/.env

# Preserve your module statuses
cp html/modules_statuses.json html_new/modules_statuses.json

# Preserve uploaded files
cp -r html/storage/app html_new/storage/app

# Rename directories
mv html html_old
mv html_new html

cPanel / Shared Hosting:

  1. In File Manager, rename your current application folder (e.g., public_html to public_html_old)
  2. Upload and extract the new release ZIP to the original location
  3. Copy your .env file from the old folder to the new folder
  4. Copy modules_statuses.json from the old folder to the new folder
  5. Copy the storage/app folder from the old folder to the new folder (this contains your uploaded files)
tip

Do not overwrite .env or modules_statuses.json with the files from the new release. Your existing files contain your database credentials and module configuration.

Step 3: Run Post-Update Commands​

Install Dependencies​

If the release does not include the vendor directory, run Composer:

composer install --no-dev --optimize-autoloader --ignore-platform-reqs

Run Database Migrations​

This applies any new database changes from the update:

# Run core migrations
php artisan migrate --force

# Run module migrations for all active modules
php artisan module:migrate --force

The --force flag is required to run migrations in a production environment.

Clear All Caches​

php artisan optimize:clear

This clears the configuration cache, route cache, view cache, and compiled files. It is equivalent to running:

php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear

Rebuild Frontend Assets​

If the release includes pre-built assets in public/build/, skip this step.

If you need to build assets:

npm install
npm run build

For servers with limited memory (4-8GB RAM):

npm install
npm run build:server:optimized

If the storage symlink was lost during the file replacement:

php artisan storage:link

Regenerate Autoloader (If Needed)​

If you installed new addon modules as part of the update:

composer dump-autoload

Step 4: Verify the Upgrade​

  1. Open your application in a browser and log in
  2. Check the dashboard loads correctly
  3. Navigate to Addons (accessible at /addons) and verify modules are listed with their correct versions
  4. Test key features your organization uses (attendance, leave, payroll, etc.)
  5. Check storage/logs/laravel.log for any errors

Set Correct Permissions (VPS)​

After replacing files, ensure permissions are correct:

sudo chown -R www-data:www-data /var/www/html
chmod -R 775 storage bootstrap/cache

Set Correct Permissions (cPanel)​

  1. Right-click the storage folder and set permissions to 775
  2. Right-click the bootstrap/cache folder and set permissions to 775
  3. Right-click the Modules folder and set permissions to 775
  4. Set the modules_statuses.json file permissions to 664

Upgrading Addon Modules​

Individual addon modules can be upgraded separately from the main platform.

Replacing Module Files Manually​

  1. Download the new addon package from your purchase dashboard
  2. Back up the existing module folder (e.g., Modules/Payroll/)
  3. Delete the old module folder from Modules/
  4. Extract the new module files into Modules/
  5. Run migrations and clear caches:
php artisan module:migrate ModuleName --force
php artisan optimize:clear
composer dump-autoload

Replace ModuleName with the actual module folder name (e.g., Payroll, TaskSystem, Recruitment).

Installing New Addon Modules via Admin Panel​

New addon modules can also be installed through the admin panel:

  1. Navigate to Addons (accessible at /addons)
  2. Click Upload Module
  3. Select the addon ZIP file
  4. The system will automatically extract files, run migrations, and enable the module
note

The upload feature installs new modules. To update an existing module to a newer version, replace the module files manually as described above.

Handling Customizations​

If you have made custom modifications to the source code, upgrading requires extra care.

Before Upgrading​

  1. Document all files you have modified
  2. Use a diff tool (such as diff, VS Code, or a file comparison tool) to track your changes
  3. Consider maintaining a list of customized files for future reference

After Upgrading​

  1. Re-apply your customizations to the new files
  2. Review the release changelog -- changes in the new version may conflict with your modifications
  3. Test thoroughly after re-applying customizations
Version Control

If you use Git to track your installation, you can use git diff to see exactly what changed between your customized version and the new release. This makes re-applying customizations much easier.

Troubleshooting Upgrades​

Migration Errors​

If migrations fail with a "table already exists" error:

# Check migration status
php artisan migrate:status

# If a specific migration was already applied manually,
# you may need to mark it as run:
php artisan migrate --force

If a module migration fails:

# Run migration for a specific module
php artisan module:migrate ModuleName --force

500 Error After Upgrade​

  1. Check storage/logs/laravel.log for the specific error
  2. Ensure .env file was preserved correctly
  3. Clear all caches: 
    php artisan optimize:clear
  4. Verify file permissions on storage/ and bootstrap/cache/

Missing CSS or JavaScript​

  1. Check that public/build/ exists and contains compiled assets
  2. If missing, rebuild assets: 
    npm install
    npm run build
  3. Clear browser cache

Module Not Working After Upgrade​

  1. Check modules_statuses.json to verify the module is set to true
  2. Run the module's migrations: 
    php artisan module:migrate ModuleName --force
  3. Clear caches: 
    php artisan optimize:clear
  4. Regenerate autoloader: 
    composer dump-autoload

Queue Workers Not Processing​

If you use Supervisor for queue workers, restart them after upgrading:

sudo supervisorctl restart opencorebs-worker:*

Rollback​

If the upgrade causes critical issues, restore from your backup:

Restore Files​

# VPS
cd /var/www
rm -rf html
mv html_old html

Restore Database​

mysql -u your_db_user -p your_database_name < backup_YYYYMMDD_HHMMSS.sql

After Restoring​

php artisan optimize:clear

Need Help?​

Last updated on