Updates and backups

#Knowing when there's an update

Once a day FusionTerm checks Docker Hub for a newer version. When there is one, admins see "FusionTerm X is available" at the top of Settings, with a dot on the Settings icon. The bottom of Settings shows your version and a Check for updates button.

The check is an anonymous request to Docker Hub — nothing about your install is sent. On closed networks, turn it off with the environment variable FUSIONTERM_UPDATE_CHECK=0.

#Updating

Docker Compose — in the folder with docker-compose.yml:

docker compose pull && docker compose up -d

docker run — download the new version, then recreate the container with the same command you used before (your data is in the volume, so nothing is lost):

docker pull hammadsaqib/fusionterm:latest
docker rm -f fusionterm
docker run -d --name fusionterm -p 5577:5577 -v fusionterm-data:/data --restart unless-stopped hammadsaqib/fusionterm:latest

Add the same -e … settings you started it with (for example -e GUACD_HOST=…).

Prefer predictable upgrades? Use a version tag such as hammadsaqib/fusionterm:1.0 (only small fixes) instead of latest.

#Automatic backup before every update

When a new version starts for the first time, it copies the database to backups/ inside the data volume before changing anything, and keeps the last 5 copies. If an update ever goes wrong, you can go back — see below.

#Backing up everything

The data volume holds the database and secret.key, the key that encrypts saved passwords. Back them up together — without the key, saved passwords can't be read.

docker run --rm -v fusionterm-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/fusionterm-data-$(date +%F).tgz -C /data .

With Docker Compose the volume name starts with the folder name (for example fusionterm_fusionterm-data) — docker volume ls shows it. Run this regularly, and keep the file somewhere safe: it contains your encrypted credentials and the key to them.

#Restoring

From a full backup file:

docker stop fusionterm
docker run --rm -v fusionterm-data:/data -v "$PWD":/backup alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/fusionterm-data-2026-10-20.tgz -C /data'
docker start fusionterm

Going back to before an update (using the automatic copy):

docker stop fusionterm
docker run --rm -v fusionterm-data:/data alpine ls /data/backups
docker run --rm -v fusionterm-data:/data alpine sh -c \
  'cp -p /data/backups/<file-from-the-list> /data/fusionterm.sqlite && rm -f /data/fusionterm.sqlite-wal /data/fusionterm.sqlite-shm'

Then start the previous version (for example hammadsaqib/fusionterm:1.0.1) with your usual command.

#Keeping the encryption key apart from the data (optional)

By default secret.key lives in the data volume next to the database, so anyone with a copy of that volume can decrypt the saved passwords. To keep them apart, store the key as a Docker secret (or any file outside the data volume) and point FusionTerm at it:

1. Copy the current key out: docker compose cp fusionterm:/data/secret.key ./fusionterm_key

2. In docker-compose.yml, give the service the secret and the variable:

   services:
     fusionterm:
       environment:
         FUSIONTERM_KEY_FILE: /run/secrets/fusionterm_key
       secrets: [fusionterm_key]
   secrets:
     fusionterm_key:
       file: ./fusionterm_key
   

3. docker compose up -d, check everything still connects, then delete /data/secret.key from the volume (docker compose exec fusionterm rm /data/secret.key). FusionTerm warns in its log while both copies exist, and refuses to start if they differ.

Keep the key file safe and backed up separately — without it, saved passwords can't be read.

#Changing the encryption key

If the key may have been exposed (a copy of the data volume went astray, someone who had server access left), make a new one. Every saved password, key, vault entry and two-factor secret is re-encrypted:

docker compose stop fusionterm
docker compose run --rm fusionterm node server/server.js rotate-key --yes
docker compose start fusionterm

The database is backed up first (/data/backups/before-key-rotation-…) and the old key is kept as secret.key.old — delete it once everything works. If any value can't be decrypted, nothing is changed. With FUSIONTERM_KEY_FILE, the new key is written to /data/secret.key.new: put it into your secret, delete that file, then start FusionTerm.

Changing the key doesn't change the passwords themselves. If a copy of the data and the old key may both have leaked, change the passwords on the servers too.