Appearance

Upgrading Growstack CRM ​

This guide explains how to upgrade an existing Growstack CRM installation when a new version is released.

Table of Contents ​

  1. Before You Begin
  2. Step 1: Backup
  3. Step 2: Enable Maintenance Mode
  4. Step 3: Download and Replace Files
  5. Step 4: Install Dependencies
  6. Step 5: Run Database Migrations
  7. Step 6: Clear Caches
  8. Step 7: Restart Queue Workers
  9. Step 8: Disable Maintenance Mode
  10. Step 9: Verify the Application
  11. Rollback
  12. Troubleshooting

Before You Begin ​

Requirements ​

  • SSH or terminal access to your server (recommended)
  • Sufficient disk space for a backup
  • A maintenance window (15–30 minutes for most upgrades)
  • The new version ZIP or release package

Check the Changelog ​

Before upgrading, review the Changelog to understand what has changed, whether database migrations are included, and any special upgrade notes for the new version.

Step 1: Backup ​

Always back up before upgrading. This allows you to roll back if something goes wrong.

Database Backup ​

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

Store the backup outside the application directory.

Files Backup ​

Back up the entire application directory, or at minimum these critical items:

bash
# Full application backup
tar -czf growstack-crm-backup-$(date +%Y%m%d).tar.gz /var/www/growstack-crm

# Or at minimum, back up your .env and storage
cp /var/www/growstack-crm/.env /var/backups/growstack-crm.env.bak
tar -czf storage-backup-$(date +%Y%m%d).tar.gz /var/www/growstack-crm/storage

Important files to preserve:

  • .env — your environment configuration
  • storage/ — uploaded files, logs, and cached data
  • Any custom files you have added

Step 2: Enable Maintenance Mode ​

Put the application in maintenance mode so users see a friendly message during the upgrade:

bash
cd /var/www/growstack-crm
php artisan down

Step 3: Download and Replace Files ​

Download the New Version ​

Download the new version ZIP from your purchase source (e.g., CodeCanyon).

Upload and Extract ​

Upload the ZIP to your server and extract it:

bash
cd /tmp
unzip growstack-crm-v2.x.x.zip

Replace Application Files ​

Copy the new files over your existing installation, preserving your .env file and storage/ directory:

bash
# Copy new files (excluding .env and storage)
rsync -av --exclude='.env' --exclude='storage/' /tmp/growstack-crm-v2.x.x/ /var/www/growstack-crm/

# Or manually copy then restore .env
cp /var/www/growstack-crm/.env /tmp/growstack-crm.env.bak
# Extract new version over existing directory
cp /tmp/growstack-crm.env.bak /var/www/growstack-crm/.env

Do NOT overwrite:

  • .env — contains your database credentials and app key
  • storage/ — contains uploaded files and logs

Do overwrite everything else, including app/, resources/, routes/, database/, public/, config/, composer.json, etc.

Fix Permissions ​

After replacing files:

bash
sudo chown -R www-data:www-data /var/www/growstack-crm
sudo chmod -R 755 /var/www/growstack-crm
sudo chmod -R 775 /var/www/growstack-crm/storage /var/www/growstack-crm/bootstrap/cache

Step 4: Install Dependencies ​

Update PHP packages with Composer:

bash
cd /var/www/growstack-crm
composer install --no-dev --optimize-autoloader

If the new version includes frontend changes, rebuild assets:

bash
npm install
npm run build

Step 5: Run Database Migrations ​

Apply any new database migrations included in the new version:

bash
php artisan migrate --force

The --force flag is required to run migrations in production mode. This is safe — migrations only add new tables or columns; they do not drop your data unless the release notes specifically state otherwise.

Step 6: Clear Caches ​

After a file update, always clear all caches so the application picks up new code:

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

Or use the convenience command:

bash
php artisan optimize:clear

Step 7: Restart Queue Workers ​

Queue workers load code into memory and will continue running old code until restarted. Restart them after every upgrade:

If using Supervisor: ​

bash
sudo supervisorctl restart growstack-crm-worker:*

If using a cron-based queue: ​

The cron-based queue:work --stop-when-empty approach restarts automatically on each cron tick. No action needed.

Step 8: Disable Maintenance Mode ​

Bring the application back online:

bash
php artisan up

Step 9: Verify the Application ​

After upgrading, verify everything is working:

  • [ ] Admin login works (/login)
  • [ ] CRM Dashboard loads (/admin/crm)
  • [ ] Contacts, Leads, and Deals pages load correctly
  • [ ] Create a test contact to verify database writes work
  • [ ] Check storage/logs/laravel.log for any new errors
  • [ ] Verify email sending works (send a test email from Settings → Email Settings)
  • [ ] Confirm queue workers are processing jobs (check the queue monitor or logs)
  • [ ] Test any features mentioned in the changelog

Rollback ​

If the upgrade causes unexpected issues:

Step 1: Restore the Database ​

bash
mysql -u growstack_crm_user -p growstack_crm < backup_YYYYMMDD_HHMMSS.sql

Step 2: Restore Application Files ​

bash
tar -xzf growstack-crm-backup-YYYYMMDD.tar.gz -C /

Or restore from your specific backups:

bash
cp /var/backups/growstack-crm.env.bak /var/www/growstack-crm/.env
# Restore original application files from the previous version ZIP

Step 3: Clear Caches ​

bash
cd /var/www/growstack-crm
php artisan optimize:clear

Step 4: Restart Queue Workers ​

bash
sudo supervisorctl restart growstack-crm-worker:*

Troubleshooting ​

Blank Page or 500 Error After Upgrade ​

  1. Check Laravel logs:
    bash
    tail -f /var/www/growstack-crm/storage/logs/laravel.log
  2. Enable debug mode temporarily:
    APP_DEBUG=true
    Then visit the site to see the error. Disable immediately after diagnosing.
  3. Ensure .env was not overwritten
  4. Run php artisan optimize:clear again

Migration Errors ​

  1. Check the specific migration error in the output
  2. If a table already exists, check php artisan migrate:status
  3. Do not run migrate:fresh — this drops all tables and deletes all data

Composer Errors ​

  1. Verify PHP version is still 8.2+: php -v
  2. Check for conflicting packages: composer diagnose
  3. Try: composer install --no-dev --optimize-autoloader --no-scripts then php artisan package:discover

Queue Jobs Not Processing ​

  1. Check Supervisor is running: sudo supervisorctl status
  2. Restart workers: sudo supervisorctl restart growstack-crm-worker:*
  3. Check worker logs: tail -f /var/www/growstack-crm/storage/logs/worker.log

Released under the MIT License.

Copyright © 2026 Growstack CRM