Upgrading Growstack CRM

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

Before You Begin
Step 1: Backup
Step 2: Enable Maintenance Mode
Step 3: Download and Replace Files
Step 4: Install Dependencies
Step 5: Run Database Migrations
Step 6: Clear Caches
Step 7: Restart Queue Workers
Step 8: Disable Maintenance Mode
Step 9: Verify the Application
Rollback
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

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:

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

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:

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:

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

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:

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

If the new version includes frontend changes, rebuild assets:

npm install
npm run build

Step 5: Run Database Migrations

Apply any new database migrations included in the new version:

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 and Rebuild Caches

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

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:

php artisan optimize:clear

Then rebuild the production caches so the application isn't left parsing config and routes from scratch on every request:

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

This matches what the web installer does automatically at the end of a fresh install — an upgrade should leave your instance just as optimized as a new one.

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:

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:

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

mysql -u growstack_crm_user -p growstack_crm < backup_YYYYMMDD_HHMMSS.sql

Step 2: Restore Application Files

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

Or restore from your specific backups:

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

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

Step 4: Restart Queue Workers

sudo supervisorctl restart growstack-crm-worker:*

Troubleshooting

Blank Page or 500 Error After Upgrade

Check Laravel logs:

tail -f /var/www/growstack-crm/storage/logs/laravel.log

Enable debug mode temporarily:
```
APP_DEBUG=true
```
Then visit the site to see the error. Disable immediately after diagnosing.
Ensure .env was not overwritten
Run php artisan optimize:clear again

Migration Errors

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

Composer Errors

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

Queue Jobs Not Processing

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

Table of Contents