Upgrade

Summary (web updater, no terminal required for migrations):

1. Admin → Diagnostics → "Take Backup" creates a verified checkpoint under storage/backups/{checkpoint_id}/ containing a gzip database dump, a copy of .env, and a storage-data.zip archive of files under storage/app/ (the updater workspace is excluded).
2. Upload the new release via your host (FTP, cPanel File Manager, or SSH), or use Admin → Diagnostics → Upload release package to validate and stage the CodeCanyon zip. When a package is staged, Apply update can publish those files from the browser. Overwrite application files but do not replace storage/ or .env when using host tools.
3. Admin → Diagnostics → "Apply Update" verifies the checkpoint on disk and re-verifies any staged zip. It enters maintenance mode, captures a fresh rollback checkpoint while writes are paused, then replaces application files when staged, runs migrate --force, and repeats the probes. A core probe FAIL blocks treating the upgrade as complete.
4. Verify the booking page and cron beacon.

Rollback: when a staged package update leaves the site in recovery, open /system/diagnostics while maintenance mode is on and use Restore from checkpoint. An already-open Admin page may receive a 503 on its next action. Restore brings back the database, .env, durable storage/ files, and application code from the verified checkpoint and private code snapshot. Native SQL dumps need the host mysql or psql client; PHP exporter dumps restore without those tools. See Rollback below.

Migrations from the browser. Step 3 runs from Admin → Diagnostics without SSH. Staged zip upload validates the package; Apply update publishes it and runs migrations. Without a staged package, Apply update runs migrations only and your host must already have the new code. The browser sends the zip in 1 MB requests, so the usual PHP upload limit does not need to exceed the full zip size. When an update fails, use Restore from checkpoint on Diagnostics before attempting manual file copies.

Before you begin

• You are the Operator (the person who bought this licence).
• You have access to the admin panel.
• Read the release notes for the new version — specifically the upgrade-impact line. Most releases are additive and safe; breaking changes are called out explicitly.

Standard upgrade procedure (web updater)

Step 1 — Take a backup (gated)

1. Go to Admin → Diagnostics (installed release version is shown on this page).
2. Click Take Backup (Filament) or 1 · Create backup checkpoint (fallback /system/diagnostics).
3. The app writes a verified checkpoint to storage/backups/{checkpoint_id}/:
   • db.sql.gz: database dump (gzip)
   • .env.bak: copy of your environment file
   • storage-data.zip: archived durable files from storage/app/ except the updater workspace
   • manifest.json: file sizes and SHA-256 hashes used to verify integrity
4. Note the checkpoint ID on screen. Apply update refuses to run migrations until the checkpoint on disk passes verification for your session. It captures a second, fresh checkpoint after maintenance starts and uses that checkpoint for recovery.

Shared hosting tip: storage/backups/ is private (outside public/) and is not web-accessible. It is included in your cPanel backup if you run one via the control panel.

Step 2 — Upload the new release package

Option A: Admin Diagnostics (validate and stage zip)

1. Download the new release ZIP from CodeCanyon.
2. Go to Admin → Diagnostics and use Upload release package. Select the zip and leave the page open while its upload and verification progress is shown.
3. When verification succeeds, the staged version appears on screen. Use Apply update (step 3) to publish these files and run migrations, or use Option B to upload via your host and run Apply update for migrations only.

Option B: Shared hosting (no SSH)

1. Download the new release ZIP from CodeCanyon.
2. Extract it locally. It ships with vendor/ bundled — no Composer step needed on your server.
3. Upload all files via FTP / cPanel File Manager, overwriting the existing files. Skip storage/ and .env — those are yours.

Option C: VPS / SSH

cd /var/www/calbok
php artisan down --retry=60
# replace files (git pull, or extract the ZIP)
php artisan up

--message was removed from artisan down in modern Laravel — maintenance mode now renders a fixed default page (or your own view via --render=view.name). --retry=60 sets the Retry-After header so well-behaved clients back off instead of hammering the site while you upgrade.

Step 3: Apply update (web updater)

1. Return to Admin → Diagnostics.
2. Click Apply Update (Filament) or 2 · Apply update (fallback).
3. The updater re-verifies your checkpoint on disk and enters maintenance mode. It captures and verifies a fresh rollback checkpoint before changing code or database schema. When a release zip is staged, it copies the package to a private immutable file and replaces application files (not .env or customer storage/app/). It then runs php artisan migrate --force. A nonzero migration exit code is treated as failure. The site stays in maintenance and Diagnostics shows a recovery state instead of success.
4. If file replacement fails before migrations start, Calbok restores the prior application files from a private code snapshot when that snapshot is complete. If restoration cannot be verified, the site stays in maintenance and Diagnostics remains available to authenticated Operators for recovery.
5. After migrations complete, all capability probes re-run automatically.
   • If a core probe FAILS (PHP version, database queue/limiter backing stores, timezone tables), the updater stays in an error state — do not mark the upgrade complete; proceed to rollback.
   • If only optional integration probes fail (mail, SMS, payment gateways, billing provider, etc.), the updater still completes; fix those warnings on Diagnostics when you are ready.
   • If all probes are OK or WARN, the upgrade is complete.

Step 4 — Verify

• Check that the admin panel loads normally.
• Run a test booking end-to-end (or at least open the booking page for a tenant and confirm it renders).
• Confirm the cron beacon probe on the Diagnostics page is green (i.e. schedule:run fired within the last tick window).

Rollback

If Step 3 fails, or if you discover a regression after the upgrade:

Option A — Restore from backup checkpoint (recommended)

1. Locate your checkpoint in storage/backups/{checkpoint_id}/.
2. Restore the database (plain SQL inside gzip, including INSERT data rows; safe for CLI import):

   # MySQL / MariaDB
   gunzip -c db.sql.gz | mysql -u USER -p DATABASE
   # PostgreSQL
   gunzip -c db.sql.gz | psql -v ON_ERROR_STOP=1 -U USER -d DATABASE
   

   When native mysqldump / pg_dump are unavailable, the app uses a PHP exporter that writes the same kind of plain SQL (not COPY ... FROM stdin). Use these pipe commands rather than pasting into a single-statement SQL client.
3. Restore .env: copy .env.bak from the checkpoint directory back to {root}/.env.
4. Restore durable files: extract storage-data.zip into your storage/ directory (merge/overwrite as needed).
5. Restore the old code: re-upload the previous release package (or git checkout the previous tag on a VPS).
6. Run php artisan config:clear && php artisan cache:clear.
7. Verify the Diagnostics page shows green.

Browser recovery (recommended after a failed Apply update):

1. Open /system/diagnostics as Operator while maintenance is on. Sign in if prompted.
2. Confirm the recovery banner and click Restore from checkpoint.
3. Type the installed release version and the failed update target version shown on screen.
4. The app verifies the checkpoint, restores database and storage, restores .env, restores prior code from the required private snapshot, clears compiled caches, and re-runs core probes. Success exits maintenance mode.

Limits: checkpoints created with native mysqldump / pg_dump require the matching mysql or psql client on the server. PHP exporter dumps restore without those binaries. If recovery cannot verify a dump format or snapshot, it stops before destructive steps. One-click code recovery requires a release staged and applied from Diagnostics. If you uploaded code using host tools, restore that code using the previous package.

Manual rollback (same checkpoint files under storage/backups/{checkpoint_id}/):

1. Import db.sql.gz with your host tools (see commands in the HTML upgrade guide).
2. Copy .env.bak to .env.
3. Extract storage-data.zip into storage/.
4. Re-upload the previous release package if code was changed outside the snapshot.

Option B — cPanel backup (shared hosting)

If you do not have a storage/backups/ checkpoint (e.g. the backup step was skipped or the backup failed), restore from your most recent cPanel full- account backup via cPanel → Backups → Restore.

Always take a backup before upgrading. Apply update verifies the checkpoint on disk and refuses to run migrations when verification fails.

Migration safety contract (normative)

Every Calbok release migration follows these rules — enforced by the release build pipeline:

Emergency contacts

• CodeCanyon support: the item page → "Support" tab.
• Documentation: docs/ in this package, or your buyer dashboard.
• Cron not firing? See docs/deployment/shared-hosting.md → "The single cron entry."