HomeBox
עברית GitHub Install

Guides

Updates

How HomeBox updates itself and your apps — with a backup first and a way back if something goes wrong.

There are two kinds of update, and they are kept apart on purpose: updates to HomeBox itself, and updates to the apps it runs.

Updating HomeBox

HomeBox checks for a new release in the background every few minutes. When one is out, a red dot appears next to Updates. Open it, read what changed, and press the button.

What happens next:

  1. A backup of HomeBox's own settings is taken.
  2. The new release is downloaded and installed.
  3. HomeBox waits for the dashboard to come back healthy.
  4. If it does not, the previous release is put back automatically.

A progress window shows each step, and the dashboard reloads itself when it is done. Your apps keep running throughout.

From a terminal:

sudo homebox self-update           # update now
sudo homebox self-update --check   # only check

"Updates are paused." If a release turns out to have a problem, it can be stopped for every box at once. The Updates tab then says so and explains why, instead of offering the button. Nothing needs doing on your side — the button comes back when a fixed release is out.

Updating apps

Every app is pinned to an exact version, so nothing changes under you unattended. The Updates tab lists two things:

Rebuilds of the version you have

Publishers re-release the same version with security fixes in its base layers. HomeBox spots this by comparing what is running against what the publisher now serves, and offers an Update button. It backs up that app, pulls, restarts it, and waits for it to be healthy — rolling back if it is not.

Newer versions

When a genuinely newer version exists, the app shows an Upgrade button. A new version may change its database on first start, so HomeBox always backs the app up before it switches.

A new major version of a database — Postgres 14 to 17, for example — is shown but never offered as a button. A database's files belong to the version that wrote them, and moving between majors needs a migration, not an image swap.

What gets backed up before an update

Only the app being updated, not the whole box. Artwork, caches and logs that the app downloads or rebuilds by itself are skipped, so these backups are usually a few megabytes. They are kept per app in /opt/homebox/state/update-backups.