Backups, Updates, and Migration

Plan recovery before changing a working installation. Keep the last known good release, a verified database backup, uploaded files, and the environment configuration needed to restore the same installation.

What needs a backup

Asset	Why it matters
Complete PostgreSQL database	Business records, users, module tables, license cache, settings, and the runtime-secret table
Local uploaded files	Images and documents are not contained in database rows
External provider files	Local CMS backups do not copy remote object stores
Environment and deployment settings	Database access, public URL, explicit secrets, process manager, proxy, and storage paths
Current release archive	Required to restore compatible application code
Custom modules and changes	A standard release does not recreate organization-specific extensions

A backup stored only on the application server can be lost with that server. Keep protected copies in a separate location and establish retention based on how much recent work you can afford to lose.

Use the CMS backup tools

Open Settings → Backups. Create a backup, review its completion and details, and download a copy. The current archive format includes a database dump, metadata, and local uploads when present.

Check the file count and database information rather than assuming a nonempty archive includes everything. Confirm that the resolved APP_ROOT points to the storage containing your actual uploads.

The archive does not replace a backup of external storage, your environment file, or infrastructure configuration. Preserve those separately.

Verify recovery

Periodically test a restore in an isolated environment using a compatible release. Protect production credentials and prevent the test instance from sending real messages or processing real payments. Coordinate any license needed for that environment; do not let a recovery test claim a live unbound license.

After restoring, confirm users, representative business records, module data, and uploaded files. A successful download is not evidence that a backup is restorable.

Apply a release manually

The CMS can check for releases and surface a signed download link in Settings → System Health. It does not automatically replace the application files.

1. Read the target release notes, runtime requirements, and any migration instructions.
2. Download the appropriate release and verify its checksum.
3. Schedule a maintenance window and prevent new writes.
4. Create a final database and file backup, plus a copy of the existing release and environment.
5. Stop all application workers and any processes that can write to this installation.
6. Replace application code in the same installation location, retaining the existing environment, persistent storage, and approved custom extensions. Inspect the archive layout before extracting; avoid an unintended nested directory.
7. Install the target release's production dependencies.
8. Run bunx prisma migrate deploy from the target release directory with the correct PostgreSQL connection.
9. Start the application and review module migration and startup logs.
10. Verify sign-in, license, settings, modules, uploads, mail, and representative real-time behavior before reopening access.

Keep the application's working directory stable: directory binding is part of the license check. Do not regenerate the compiled Prisma client in a downloaded release.

Roll back carefully

Restoring old application files alone may not be compatible with a database that has already received new migrations. Review the release's recovery instructions. If schema compatibility is uncertain, restore the matching pre-update database and files together with the old release.

Restoring a database loses changes made after that backup. Keep users out until the recovery outcome is verified. A Prisma migration bookkeeping command does not undo SQL changes or restore lost data.

Move to another server or hostname

1. Prepare the destination runtime, PostgreSQL, storage, and HTTPS ingress.
2. Record the new hostname, outbound IP, application path, and storage location.
3. Take an initial copy, then schedule a final maintenance window.
4. Stop writes on the old installation and take the final database and file backup.
5. Restore the complete database, including the runtime application key, and copy uploads to the destination's resolved storage path.
6. Update DATABASE_URL, APP_ROOT, and APP_URL as required.
7. Reissue the license for the destination before its first remote validation. Keep the old installation stopped.
8. Point DNS at the destination and verify HTTPS.
9. Test sign-in, license validation, files, mail links, provider callbacks, and WebSocket behavior.

Do not leave two production installations writing to divergent copies of the same business data. Retain the old server and backups until the destination is verified, then retire them according to your retention policy.