Upgrading Forkiva

Forkiva is upgraded as one Laravel release. Application code, self-contained add-on packages, Composer dependencies, and generated public/build/ assets must come from the same release. Each add-on is installed and upgraded only as its single package.

The php artisan forkiva:upgrade command applies module migrations, synchronizes permissions and default roles, seeds required notification data, and clears stale caches. It does not download source files, install Composer/Yarn dependencies, build Vue assets, back up the database, or validate the application for you.

Before upgrading

1. Read the release notes and confirm that every installed add-on supports the new version.
2. Create a verified database backup and application/storage backup.
3. Rehearse the upgrade against a staging copy of production data.
4. Confirm the new release contains every enabled module and purchased add-on.
5. Record the current version and a tested rollback procedure.

Never overwrite .env, rotate APP_KEY, delete storage/, or run fresh-install seeders during an upgrade.

Prepare the new release

From the new Laravel application root, install locked dependencies and build the web interface:

composer install --no-dev --prefer-dist --optimize-autoloader
yarn install --frozen-lockfile --production=false
yarn check:modules
yarn build

Set all production VITE_* variables in the build environment before yarn build. Same-origin deployments do not need VITE_API_URL. Preserve VITE_STORAGE_ENCRYPTION_KEY; changing it invalidates existing encrypted browser storage and signs users out.

Use the official prebuilt release package if the production host cannot run Composer and Yarn. Do not assemble assets from partial source folders or edit public/build/ manually.

Deploy and upgrade

An atomic release directory or deployment symlink is preferred. Share or securely copy the existing .env and persistent storage into the new release, while keeping the new release's code and generated assets together.

When an in-place deployment is unavoidable, enable maintenance mode before replacing files:

php artisan down --retry=60

After the complete release and dependencies are present, run:

php artisan forkiva:upgrade
php artisan storage:link
php artisan queue:restart

If the upgrade succeeds, activate the new release and disable maintenance mode:

php artisan up

If migration or upgrade output reports an error, do not continue the cutover. Keep the application in maintenance mode and follow the tested rollback procedure. Database rollbacks require release-specific review; do not use destructive broad rollback or refresh commands on production.

Verify the release

• Confirm the home page and authenticated Vue routes load through the Laravel hostname.
• Confirm /api/v1/... requests reach the same Forkiva application and return the standard response envelope.
• Test login, logout, permissions, POS, uploads/downloads, and the most important workflows for every enabled module.
• Confirm queue workers are running the new release and scheduled jobs execute.
• Test mail, storage, PDF/receipt generation, and enabled integrations.
• Review browser console/network errors, Laravel logs, worker logs, and monitoring.
• Confirm APP_ENV=production, APP_DEBUG=false, HTTPS, and the expected application URL.

Keep the previous release and its assets available long enough for rollback and for open browser tabs/service workers to update. Do not replace the entire public/ directory blindly because it also contains application assets and the storage link.

Shared hosting

Shared-hosting upgrades still require a prebuilt, tested release and a database backup. Do not extract an archive over the live site without a maintenance window and rollback plan. Preserve .env and storage, deploy all other release files together, then run the upgrade command through an approved hosting terminal/deployment task. If the host cannot provide this safely, ask the provider or a developer to perform the upgrade.

Common issues

Issue	Action
Missing module classes or routes	Confirm the complete module package is present, then reinstall Composer dependencies and rebuild.
Old or missing Vue pages	Deploy the matching public/build/, clear caches, and allow the service worker/open tabs to update.
Permission denied	Correct ownership and least-privilege write access for storage/ and bootstrap/cache/.
Database error	Stop the deployment, preserve logs, and restore through the tested rollback plan if required.
Queue jobs use old code	Restart managed workers after the release is activated.