Upgrading Your Node

Overview

Upgrading replaces your node's container with one running a new release image, while keeping the same persistent data volume, hostname and admin credentials. Starting or restarting an existing container never upgrades it: the container keeps its installed image until you replace it.

These steps apply to the standard Docker installation, with the container unolock-node and the volume unolock-node-data. If you customized the volume name, certificate settings or other options, record them and reapply them when you create the replacement container. See Configuration.

If your node is part of an active/standby pair, do not use this procedure. See Upgrading a cluster.

Before every upgrade

Read the new release notes and get their exact image reference. Keep any supplied checksums and verification files with your installation record.
Create and verify a fresh version-4 backup, and preserve the exact live config.
Record the current image ID, container options, certificate mode, node health and hosted-client status.
Confirm that the previous image and your recovery procedure remain available.

Upgrade an existing node

Read the new release's upgrade notes, including any required migration steps. Get updated release files if the notes require them.
Save a reference to the exact currently installed image before changing anything:
```
sudo docker image inspect "$(sudo docker inspect unolock-node --format '{{.Image}}')" \
  --format '{{index .RepoDigests 0}}'
```
Keep the complete printed reference with your installation notes. It lets you select this same image for recovery after an upgrade. Check Diagnostics and record any existing health failures.
Create and verify a fresh backup using Backup and Recovery. Preserve the exact live configuration separately as that page describes. Do not proceed if backup verification fails.
Select the new release's immutable image reference from its release notes and download it before stopping the old container:
```
read -r -p 'New image reference from release notes: ' UNOLOCK_IMAGE
sudo docker pull "$UNOLOCK_IMAGE"
```
Continue only if the pull succeeds. Tell Safe users the node will be unavailable while you replace and unlock it.
Stop and remove the old container:
```
sudo docker stop unolock-node
sudo docker rm unolock-node
```
Keep unolock-node-data. Do not run docker volume rm: the replacement container needs that same data volume.
Create the replacement container with your original hostname and the new image. Reapply any custom settings now:
```
read -r -p 'Original permanent node hostname: ' UNOLOCK_DOMAIN
sudo sh packaging/docker/run-node.sh --domain "$UNOLOCK_DOMAIN" --image "$UNOLOCK_IMAGE" --engine docker
```
This reuses the existing unolock-node-data volume. Sign in with your existing admin passkey and PIN. Do not register a new administrator. If the node unexpectedly asks you to register, stop and check that you used the original data volume and hostname.
Open /admin, Sign in, and choose Unlock Node. Follow any migration steps required by the release. Check Clients: use the offered rebuild or signing action if required, and wait for it to finish. Rebuild not needed means the browser app already matches this image, but it still needs a valid signature.
Run the Diagnostics health checks. Open an existing Safe, accept a browser app update if one is offered, and check a note and a test file upload and download. If you use Vault Messaging across nodes, test a message and attachment across that boundary too.

Confirm the installed image:

sudo docker inspect unolock-node --format '{{.Image}}'

Note

A successful image download or a running container does not prove the upgrade succeeded. Your existing Safes and data must still work.

If an upgrade fails

Warning

Do not run an older image against the upgraded data volume. Startup may have changed the database format.

Returning to an older release requires restoring the backup made before the upgrade into a separate, empty volume. Before an upgrade, retain the verified version-4 backup, the previous image reference, the permanent domain and the host configuration needed to expose the same WebAuthn RP ID.

To roll back:

Stop the upgraded node and prevent it from restarting or accepting traffic.
Create a separate empty recovery volume.
Verify the pre-upgrade backup again.
Restore it into the recovery volume using the documented manual procedure in Backup and Recovery.
Start the previous image, using its saved full reference, in isolation at the original permanent domain.
Verify admin sign-in with the recovery key, node unlock, health checks, Safe access, file downloads and any cross-node messaging you use.
Move traffic only after those checks pass.

Data written after the pre-upgrade backup is outside that rollback point. Do not copy individual database, WAL, archive, verifier, Tor or cluster files between the upgraded and restored volumes.

FAQs

Does restarting the container pick up a newer release?

No. Starting or restarting an existing container keeps its installed image. Follow the upgrade procedure to replace the container with a new image.

Will I lose my data when I remove the old container?

No, as long as you keep the unolock-node-data volume. Removing a container does not remove its volume. Never run docker volume rm during an upgrade.

Do I need to rebuild the browser client after upgrading?

Check Clients after every image upgrade. If it reports Rebuild required, use the offered rebuild and signing action and wait for it to finish.

Can I go back to the previous image if something breaks?

Not on the upgraded volume. Restore your pre-upgrade backup into a separate, empty volume and start the previous image against that.

How do I upgrade an active/standby pair?

Do not apply these standalone steps to each member independently. Both members must run the same immutable image. See Active/Standby and Failover.

Back to Self-Hosted Overview