Skip to main content
Use a clone of your existing installation and its data. A fresh empty installation is useful as a reference, but does not test your upgrade. You do not need to replace the production server to upgrade it.
1

Record the baseline

Record app and dependency versions, Compose project/chart, volumes, secrets and enabled integrations. Choose your upgrade stops. Record a few existing surveys, response counts, uploaded files and user roles to check after each stop.
2

Create an isolated copy

Restore a coordinated backup, or clone a consistently stopped VM and its disks. A VM snapshot does not include external databases, buckets or shared Redis.Before starting the clone, point it at separate datastores and storage. Block production SMTP, webhooks, scheduled integrations and other outbound effects; use test recipients/endpoints when testing delivery. Keep it private and restrict access to copied production data.
3

Configure the test origin

Set the test WEBAPP_URL, any separate PUBLIC_URL, and the auth base URL (NEXTAUTH_URL on older deployments, or BETTER_AUTH_URL). Register the test SSO callback separately and update storage CORS. Use the development license issued for this environment; contact support if you need one.Preserve encryption keys needed to read restored data. Separate test service credentials from production where possible, updating both ends together. Do not replace encryption keys just to rename the host.
4

Prove the old version works

Start the clone on the recorded source version. Check existing-user sign-in, stored responses and files. Fix any restore, hostname, network or license problems before trying an upgrade.
5

Upgrade one stop at a time

Follow the release’s Before / During / After checklist and the matching deployment procedure. Record configuration changes, commands, elapsed time and exit status. Wait for migrations and required backfills to finish before moving to the next stop.Stop on failed migrations, missing services, broken SSO or unexpected permission results. Do not mark a failed migration applied to continue. Keep redacted logs for troubleshooting.
6

Test recovery and write the production runbook

Restore the previous coordinated state and matching images on the test environment. Prove it starts and the baseline still works. Then record the exact successful route and a maintenance window that includes recovery time. Production must use the same tested artifacts and configuration changes.

Acceptance at every stop

Run the deployment check when a matching published image exists. It creates test data; use a dedicated workspace. Older releases may not have a matching check image—use the manual checks above instead. A green health endpoint or skipped test is not sufficient acceptance.