Upgrade Guide

Component	What Happens	Your Data Affected?
PHP source code	All app/, routes/, config/ files are replaced with the new version	No — your data is in the database, not in PHP files
JavaScript / CSS	All resources/js/ and compiled public/build/ files are replaced	No — UI code doesn't store data
Database schema	New tables are CREATED (never dropped). New columns are ADDED to existing tables (never removed)	No — existing data is untouched
Permissions	New permissions are ADDED. Existing permissions remain unchanged	No — your custom role assignments are preserved
SaaS Plans	Default plans are created if they don't exist. Existing plans are NOT overwritten	No — if you already customized plans, they stay as-is

Your Data	Status	Explanation
Shipments	100% Safe	The shipments table is never touched by migrations. All your tracking numbers, statuses, and history remain exactly as they are.
Clients / Customers	100% Safe	The customers table is never modified. Names, addresses, phone numbers — all preserved.
Invoices	100% Safe	All invoices, payments, and billing history remain in the invoices table unchanged.
Users & Passwords	100% Safe	User accounts, hashed passwords, and profile data are never touched. Users can log in normally after the upgrade.
Settings / Configuration	100% Safe	The settings table stores your company profile, branding, SMTP config, API keys, etc. This table is NEVER modified by migrations.
Branches	100% Safe	All branch data (names, addresses, codes) remains unchanged.
Notification Channels	100% Safe	Your SMTP, Twilio, UltraMsg configurations in notification_channels are preserved. New channels are only added if they don't exist yet.
Uploaded Files	100% Safe	Logos, labels, attachments in storage/app/ are never deleted during upgrade.
.env File	100% Safe	Your environment configuration (database credentials, APP_KEY, mail settings) is never overwritten.
Custom Roles	100% Safe	If you created custom roles, they remain. The seeder only updates the 5 default roles (super-admin, admin, employee, driver, customer).

Step 1: Create a Full Backup

This is the most important step. Create a backup of both your database and files.

Database Backup (via command line):

# Replace with your actual database credentials
mysqldump -u your_db_user -p your_database_name > backup_v1.3.1_$(date +%Y%m%d_%H%M%S).sql

# Verify the backup file was created and has content
ls -lh backup_v1.3.1_*.sql

Database Backup (via phpMyAdmin):

1. Open phpMyAdmin in your browser
2. Select your Deprixa Plus database
3. Click "Export" tab
4. Select format: SQL
5. Click "Go" to download the .sql file
6. Save this file in a safe location outside your server

Files Backup:

# Backup the entire application directory
cp -r /var/www/deprixa-plus /var/www/deprixa-plus-backup-v1.3.1

# Or create a compressed archive
tar -czf deprixa-plus-backup-v1.3.1.tar.gz /var/www/deprixa-plus

Step 2: Check System Requirements

Verify your server meets the requirements for the new version:

Component	Required	Check Command
PHP	8.2+	php -v
MySQL	8.0+ (or MariaDB 10.6+)	mysql --version
Composer	2.6+	composer --version
Node.js	20+ LTS	node -v
Disk Space	At least 500 MB free	df -h

Step 3: Note Your Current Version

# Check your current version
php artisan about | grep -i version

# Or check in the browser at:
# Settings → Updates → Current Version

Step 4: Inform Your Team

If other people use the system, let them know you're about to upgrade. The system will be in maintenance mode for 2-5 minutes during the upgrade. Active sessions will not be lost, but users won't be able to access the app during that window.

Step-by-Step:

1. Log in as Super Admin
   Only Super Admin users can access the update module. Navigate to Settings → Updates.
2. Activate Your License (if not already done)
   Enter your Envato Purchase Code and your name as registered on CodeCanyon. Click "Activate License". The system validates your purchase code against the license server.
3. Check for Updates
   Click the "Check for Updates" button. If a new version is available, you'll see a banner with:
   • Current version vs. new version number
   • Download size
   • Summary of changes from the changelog
4. Click "Apply Update"
   The system automatically:
   1. Downloads the update package from the update server
   2. Enables maintenance mode (users see a "Maintenance" page)
   3. Replaces application files (PHP, JS, CSS)
   4. Runs database migrations (creates new tables, adds new columns)
   5. Syncs permissions and SaaS plans via seeders
   6. Clears all caches
   7. Disables maintenance mode
5. Verify
   The progress terminal shows each step in real time. When complete, the current version badge updates to the new version. Navigate around the app to confirm everything works.

Step 1: Download the New Version

Download the latest version from CodeCanyon (your Envato Downloads page). You'll receive a ZIP file like deprixa-plus-v1.4.0.zip.

Step 2: Enable Maintenance Mode

cd /var/www/deprixa-plus
php artisan down --secret="upgrade-secret-token"

# You can still access the app via:
# https://yourdomain.com/upgrade-secret-token

Step 3: Replace Application Files

Replace these directories with the new version:

# Extract the new version to a temporary directory
unzip deprixa-plus-v1.4.0.zip -d /tmp/deprixa-new

# Replace application code (preserving .env and storage)
rsync -av --exclude='.env' \
          --exclude='storage/app/' \
          --exclude='storage/logs/' \
          --exclude='storage/framework/sessions/' \
          --exclude='storage/framework/cache/' \
          /tmp/deprixa-new/ /var/www/deprixa-plus/

# Alternative: Replace folder by folder
cp -r /tmp/deprixa-new/app/ /var/www/deprixa-plus/app/
cp -r /tmp/deprixa-new/config/ /var/www/deprixa-plus/config/
cp -r /tmp/deprixa-new/database/ /var/www/deprixa-plus/database/
cp -r /tmp/deprixa-new/public/ /var/www/deprixa-plus/public/
cp -r /tmp/deprixa-new/resources/ /var/www/deprixa-plus/resources/
cp -r /tmp/deprixa-new/routes/ /var/www/deprixa-plus/routes/
cp /tmp/deprixa-new/composer.json /var/www/deprixa-plus/composer.json
cp /tmp/deprixa-new/composer.lock /var/www/deprixa-plus/composer.lock

Step 4: Install Dependencies

cd /var/www/deprixa-plus

# Install PHP dependencies
composer install --no-dev --optimize-autoloader

# If JS is NOT pre-compiled in public/build/, also run:
# npm install && npm run build

Step 5: Run Database Migrations

# Run pending migrations (creates new tables, adds columns)
php artisan migrate --force

# This is SAFE — it only runs migrations that haven't run yet
# Your existing data is NOT affected

Step 6: Sync Permissions and SaaS Plans

# Add new permissions to the system (does NOT remove existing ones)
php artisan db:seed --class=RolesAndPermissionsSeeder --force

# Add new SaaS plans (does NOT overwrite existing plans)
php artisan db:seed --class=SaasPlansSeeder --force

Step 7: Clear Caches and Optimize

# Clear all caches
php artisan optimize:clear

# Rebuild optimized cache
php artisan optimize

# Clear compiled views
php artisan view:clear

Step 8: Set Permissions and Go Live

# Fix file permissions (Linux)
chown -R www-data:www-data /var/www/deprixa-plus
chmod -R 755 /var/www/deprixa-plus/storage
chmod -R 755 /var/www/deprixa-plus/bootstrap/cache

# Disable maintenance mode
php artisan up

Table Name	Purpose	Records Seeded
contracts	Customer contracts with rate cards, terms, signatures	0 (empty)
commission_rules	Commission configuration per organization	0 (empty)
commissions	Individual commission transactions linked to shipments	0 (empty)
saas_plans	Subscription plan definitions with limits	5 default plans
saas_subscriptions	Organization subscription records with status lifecycle	0 (empty)
saas_wallets	Organization wallet balance	0 (empty)
saas_wallet_transactions	Wallet credit/debit ledger	0 (empty)
saas_invoices	SaaS billing invoices	0 (empty)
notifications	Laravel DatabaseNotifications (UUID primary key)	0 (empty)
personal_access_tokens	Extended Sanctum API tokens with org scoping	0 (empty)
integrations	Third-party service configurations	0 (empty)

Important: All new tables are created with Schema::hasTable() checks — if the table already exists (e.g., from a partial previous upgrade), it is skipped safely.

Category	New Permissions
SaaS (5 new)	saas.billing.admin, saas.plans.manage, saas.subscriptions.manage, saas.wallets.manage, saas.invoices.manage
Contracts (3 new)	contracts.view, contracts.create, contracts.manage
Commissions (2 new)	commissions.view, commissions.manage

These permissions are automatically added to the super-admin and admin roles by the seeder. Your custom roles will need to be manually updated if you want them to access the new modules.

The following tables are never touched during the upgrade — your data remains exactly as-is:

shipments, customers, invoices, invoice_items, users, settings, branches, services, rates, rate_zones, shipment_statuses, notification_channels, notification_rules, notification_logs, activity_log, organizations, and all other existing tables.

#	Check	How to Verify
1	Login works	Log in with your admin account. Verify the dashboard loads correctly.
2	Version number updated	Go to Settings → Updates. The current version should show the new version.
3	Existing shipments visible	Navigate to Shipments. Verify your existing shipments are listed with correct data.
4	Settings preserved	Go to Settings → Company. Verify your company name, logo, and contact info are unchanged.
5	Branding intact	Check your logo in the sidebar, primary color, and login page appearance.
6	SMTP works	Go to Settings → Notifications. Send a test email to verify SMTP is still configured.
7	Users can log in	Ask a team member to log in with their existing credentials.
8	New modules appear	Check the sidebar for new items: Contracts, Commissions (under Finance).
9	Roles & Permissions	Go to Settings → Roles & Permissions. Verify new permissions appear (SaaS, Contracts, Commissions).
10	Create a test shipment	Create a new shipment to verify the full workflow still works end-to-end.

Restore Files

# Put the app in maintenance mode
php artisan down

# Restore from backup
cp -r /var/www/deprixa-plus-backup-v1.3.1/* /var/www/deprixa-plus/

# Or extract from archive
tar -xzf deprixa-plus-backup-v1.3.1.tar.gz -C /var/www/

Restore Database

# Drop and recreate the database, then import
mysql -u your_db_user -p your_database_name < backup_v1.3.1_20260511.sql

Go Live

# Clear caches and bring the app online
php artisan optimize:clear
php artisan up

From Version	To Version	Method	Notes
v1.0.x	v1.4.0	Manual (Method 2) or Automatic	Direct upgrade. All intermediate migrations run automatically in sequence.
v1.1.x	v1.4.0	Manual or Automatic	Direct upgrade. Same process.
v1.2.x	v1.4.0	Manual or Automatic	Direct upgrade. Same process.
v1.3.0	v1.4.0	Manual or Automatic	Direct upgrade. Same process.
v1.3.1	v1.4.0	Manual or Automatic	Direct upgrade. Most common scenario for CodeCanyon buyers.
v1.3.2	v1.4.0	Manual or Automatic	Direct upgrade. Minimal changes needed.