Skip to main content
Version: 1.0

Upgrading

A Fadebox upgrade is a new app image: pull it, recreate the app container, and the schema migrates itself on the way up. The database container, your runtimes and everything running on them stay where they are. What each release changed, and whether it asks for anything beyond the image, is in the release notes.

Before you upgrade​

  • Read the release notes for every release between yours and the target. Each section ends with its upgrade notes — a schema change, an ingress stack to reinstall, a setting that moved — or says there are none.

  • Check the license horizon. A paid license covers the releases published before its updates covered until date, and a build past that date refuses to start, naming both dates, rather than running unlicensed. Administration → License shows the horizon, with the version and build date you are on now in the row above it; see Renewal. The Free tier has no horizon.

  • Back up the database, and keep the .env beside the compose file with it: FADEBOX_ENCRYPTION_KEY is what makes the stored credentials in that backup readable again, and the installation ID in the database is what your license is issued for.

    docker compose exec db pg_dump -U fadebox -Fc fadebox > fadebox-$(date +%F).dump

  • Pick a quiet moment. A deploy or stop still running when the app goes down is interrupted: after the restart that instance reads ERROR with the message Interrupted by an application restart — the previous deploy or stop never finished, its containers — if any were created — are still on the runtime, and it can be deployed or stopped again. Instances that were simply running are not touched.

Pulling the new release​

The installation compose file pins the release line, fadebox/fadebox:1.0, so a patch is a pull:

docker compose pull app
docker compose up -d app
docker compose logs -f app      # migrations run before the app listens

A new minor is the same two commands after changing the tag in the compose file (1.0 → 1.1); so is a patch on an installation pinned to an exact version (1.0.1 → 1.0.2). Skipping releases is fine as far as the schema goes — every migration in between runs, in order — but read the notes of each release you skip. latest follows the newest release of any line, which is why it belongs in no compose file that is meant to stay put.

While the app container restarts, the UI and API are down and a CLI call fails. Nobody is signed out: the session lives in an encrypted cookie, and the keys in .env have not changed. Instances keep running and their URLs keep answering, with one exception — on a runtime that requires a sign-in, every request to an instance URL is checked with Fadebox first, so those URLs answer errors until the app is back.

After the upgrade​

  • Check the version in the sidebar footer or on the License page — see Which version you are running.
  • Download the CLI again from the server: it hands out the CLI it was released with, so the copy on your machine is behind until you do (Install), and fadebox --version says which one you have. A pipeline that fetches the CLI from the server at the start of each run moves with it on its own.
  • The ingress stack is not upgraded with the app. The Traefik and socket-proxy images it installs on a runtime are pinned per release; when a release moves them — its notes say so — press Reinstall / Upgrade on that runtime's ingress card, one runtime at a time. That briefly takes ingress down for every instance on that host, and issued certificates survive it. Nothing else on a runtime host changes with a Fadebox release.
  • The bundled catalog is packaged per release. When an entry you imported has a newer version in the new snapshot, the template shows an update hint — see The catalog.

Going back​

Nothing about a downgrade is automatic. Within a line, going back to an earlier patch is a tag change as long as no release in between changed the schema — the release notes say when one does, and none in 1.0.x has so far. Across a schema change, the older release does not know the migrated database: restore the backup you took before the upgrade, then start the older image against it.

PostgreSQL​

The compose file's postgres:18 is yours. A Fadebox upgrade never changes the database image, and moving to a new PostgreSQL major is the usual dump-and-restore, done on its own.