Upgrading¶

Ribbon is in development, so upgrades matter more than they will later. The short version:

cd ribbon                 # the folder with your docker-compose.yml and .env
docker compose pull
docker compose up -d

Your data volume is kept and migrated in place the first time the new version starts. Check the version afterwards in Settings → About, in the sidebar footer, or at /api/health:

{ "ok": true, "version": "0.3.0-dev.2", "commit": "a5c662f" }

Before you upgrade¶

Take a backup. Settings → Data → Back up now, then download it. See Backups & restore.
Read the changelog for anything marked as a heads-up or a breaking change.
If you build from source, git pull first, then docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.

Downgrading is not supported

Database migrations run forward only. If an upgrade goes wrong, restore the backup you took beforehand into the older image rather than pointing an old image at a migrated database.

Which tag should I run?¶

Tag	What it is	Use it for
`dev`	Built from every push to `main`. It moves.	Trying Ribbon today. There is no release yet.
`sha-<short>`	One specific commit of `main`.	Staying put on a build you tested. Set `RIBBON_TAG=sha-a5c662f`.
`0.3.0-beta.1`, ...	Pre-releases. Not yet published.	Testing a release candidate.
`0.3`, `latest`	Stable releases. Not yet published.	Normal installs, once there is a stable release.

Until the first release is cut, RIBBON_TAG=latest (the compose default) has nothing to pull, so keep RIBBON_TAG=dev in your .env.

Version-specific notes¶

Coming from a version before accounts¶

Older builds had a single shared passcode (APP_PASSCODE) and no sign-in. After updating, the first visit asks you to create the owner login. Nothing is wiped, and no Welcome setup is asked for, because your ledger already exists (installs that already have data count as set up). APP_PASSCODE no longer does anything and can be removed from .env.

Moving to 0.3.0-dev.2¶

Heads-up: with no SETUP_CODE, the first owner can now only be created from your home network. If your server is reachable from the internet and you have not created the owner yet, set SETUP_CODE first. (ALLOW_PUBLIC_SETUP=true restores the old behaviour; it is not recommended.)
Password hashing is stronger. Old hashes keep working and are upgraded when the owner next signs in.
docker-compose.yml now drops all Linux capabilities and sets no-new-privileges. If you use your own compose file, copy those two lines.

See the changelog for the full list.

Rolling back¶

docker compose down (not down -v; that deletes your data).
Set RIBBON_TAG to the previous tag or sha-....
Restore the backup you took before upgrading (how).
docker compose up -d.