Skip to main content

Upgrade and rollback

An upgrade is one command. It never starts without a fresh backup, keeps what is needed to come back, and leaves a report you can read in the application.

At a glance​

./liberty upgrade — what one command does1 · Checkdoctor (advisory)2 · Keep imagerollback-<stamp>3 · Backupstops here if it fails4 · Pull + recreatesame overlays as installed5 · Migrationsapps wheel + schemas6 · Reportthen statusSomething went wrong?./liberty rollback: previous image + this backupDeploy → History → Upgradesversions before / after, every step, migrations

Docker​

cd liberty-next/release
git pull                                  # the scripts of the new release
./liberty upgrade                         # to the latest release
./liberty upgrade --tag 7.0.58            # or to a given release (kept in .env)

What the command does, in order:

StepDetail
1. CheckRuns doctor. Problems are reported but do not stop the upgrade — an upgrade is often what fixes them.
2. Keep the imageThe image now running is tagged locally rollback-<date> so that it can be started again.
3. Backupbackup of every volume and of the apps folder, kept --keep days (30 by default). If the backup fails, the upgrade stops and nothing is changed.
4. Pull and recreateThe new image is pulled and the containers recreated with the recorded compose files — HTTPS and the licensed apps stay in place.
5. Apps and migrationsWith --apps <wheel>, the new apps bundle is installed (with its merge plan); then the pending schema migrations are applied.
6. ReportThe report is recorded and status is printed.

Downtime is the time the container takes to restart, usually well under a minute.

Upgrading the licensed apps​

./liberty upgrade --apps ./liberty_apps-7.0.58-py3-none-any.whl

Framework and apps are upgraded in one run. To refresh the apps alone, without a new framework image: ./liberty apps <wheel>.

Python install​

liberty-ops upgrade                                       # framework to the latest release
liberty-ops upgrade --version 7.0.58                      # a given release
liberty-ops upgrade --apps ./liberty_apps-7.0.58-py3-none-any.whl

Same sequence: doctor → backup (the only step that can stop the upgrade) → pipx upgrade (or the pinned version) → the apps wheel → liberty-admin migrate → service restart and wait for /ready → report → status. --no-restart leaves the restart to you; --backup-dest chooses where the backup goes.

Run it as the service user with its environment loaded, as for every liberty-ops command.

The upgrade report​

Each upgrade and each rollback records a report: versions before and after, image tag, compose files, backup folder, doctor findings, the result of every step and the migrations applied. It is stored with the configuration (.versions/upgrades/), and on Docker a copy is also written in the backup folder.

Open it in Liberty Next → Deploy → History → Upgrades. Each entry shows its component:

EntryRecorded by
Stack./liberty upgrade, ./liberty rollback, liberty-ops upgrade — the report described above.
Framework, AppsA change of version noticed when the server starts — shown with the release notes of the new version.
<app> schemaliberty-admin migrate — the migrations applied to an application database.
framework-schemaColumns the server added to its own tables when a new release needed them.

Schema migrations​

The framework creates and completes its own tables when it starts. The licensed apps' databases change through migrations shipped in the apps wheel:

  • ./liberty upgrade and liberty-ops upgrade apply them;
  • ./liberty status, ./liberty doctor and the server log at start-up say when some are pending;
  • ./liberty migrate --dry-run lists them, ./liberty migrate applies them;
  • with LIBERTY_AUTO_MIGRATE=1 in .env, the server applies them itself at start-up.

Every run is recorded in Liberty Next → Deploy → History → Upgrades. For a database whose recorded version is ahead of its real tables, liberty-admin migrate --app nomasx1 --stamp <revision> sets the version without running anything, then applies what remains — see CLI.

Rollback​

./liberty rollback            # asks for confirmation
./liberty rollback --yes

The command starts again the image kept before the last upgrade and restores the backup taken just before it. Everything written since that backup is lost — hence the confirmation. The report of the upgrade is kept, and the rollback gets its own.

On a Python install, liberty-ops rollback reinstalls the previous framework version and restores the backup taken before the upgrade. pipx keeps no copy of the previous apps wheel: pass it with --apps <previous wheel> to downgrade the apps too.

To go back further than the last upgrade: ./liberty restore <backup folder> and ./liberty upgrade --tag <release>.

Docker Swarm​

./liberty does not drive a swarm. Take a backup with ./backup.sh, then:

docker service update --image ghcr.io/fblettner/liberty-next:7.0.58 liberty_liberty-next
docker exec -u liberty $(docker ps -qf name=liberty_liberty-next) liberty-admin migrate
docker service rollback liberty_liberty-next      # if something is wrong

Or set LIBERTY_IMAGE_TAG in .env and run ./deploy-swarm.sh again.

Versions​

ChangeWhat to expect
Patch (7.0.57 → 7.0.58)Fixes and features; the configuration stays compatible; database changes only add tables or columns.
A larger stepThe release notes say what to check before and after.

Read the release notes before upgrading: Liberty Next → Document → Release notes shows those of the running version.

Tips​

  • Pin the release in production (--tag) and upgrade on purpose, a test server first.
  • Run ./liberty doctor before the upgrade: a problem reported there is easier to fix before than after.
  • After the upgrade, sign in, open a screen of each application and run a Nomaflow job by hand.
  • Keep the backup of the upgrade until the next one has run.