Skip to content

Updating Ferrule

Ferrule never updates itself. Nothing changes until you redeploy, and an update keeps everything Ferrule has recorded.

Before you update

Keep a copy of these somewhere outside the stack, such as your password manager. They're the things an update can't bring back if they go missing:

  • SETTINGS_KEY, if you set it: without it, local users and alert thresholds can't be read.
  • BACKUP_KEY, if you set it: without it, no backup can be restored.
  • Your settings: the ferrule.env the setup wizard gave you, or the stack's environment variables. For a fresh copy, open Settings → Stack environment, set Lines to everything not at its default, for a new stack, and click Download ferrule.env. Secrets in it show as <keep the value set now>, so copy those from the stack itself.

Which version runs

FERRULE_VERSION picks the release, such as 0.9.0. The setup wizard writes it into ferrule.env, so the version is pinned until you change it. The version running is shown at the foot of every page, as Ferrule 0.9.0.

Releases and what changed in each are listed at https://github.com/ferrulehq/ferrule-deploy/releases.

Pinned or not

Keep FERRULE_VERSION set, and change it when you choose to update. If you remove the line, each redeploy runs the release that the deploy repository's docker-compose.yml names, which is the newest. Never set it to latest.

Update

  1. Open the ferrule stack and find Environment variables.
  2. Change FERRULE_VERSION to the new release, such as 0.9.1.
  3. Click Pull and redeploy, and confirm.

In the folder where you cloned ferrule-deploy:

  1. Change FERRULE_VERSION in .env to the new release.

  2. Get the newest compose files, then the new image, and restart:

    git pull
docker compose pull && docker compose up -d

If you use an extra compose file, such as a backup share's, name the same files with -f on both docker compose commands as you do normally.

Docker downloads the new image and restarts the containers. Give ferrule about a minute to turn healthy, then check the version at the foot of the page.

What survives an update

Everything Ferrule keeps is on Docker named volumes, and redeploying never removes a volume:

Volume Holds
ledger-data The archive: outages, alerts, events, the audit log, users, the license, inventories
vm-data The history behind the graphs
postgres-data The reporting database, if you use it
gotify-data, igotify-data, apprise-config The bundled Gotify, iGotify and Apprise, if you use them

Portainer shows them with the stack's name in front, such as ferrule_ledger-data. Don't remove them to "start clean": the archive is the record the controller can't give back. If you have backups, a removed archive is restored from them.

If something's wrong

What you see What to do
manifest unknown There's no release with that number. Check FERRULE_VERSION for a typo
The page still shows the old version Check the new FERRULE_VERSION was saved, then redeploy again. With Compose, run docker compose pull first
Ferrule stops with a configuration message in its log The new release checks something the old one didn't. The message names the variable to fix

More in Troubleshooting.