Upgrading Safely

Moving to a new version of HiddenForge keeps your .onion address, as long as you keep your key folder. The upgrade never touches existing keys. Here's the safe way to do it.

Before you start

Back up your key folder if you haven't lately. An upgrade shouldn't lose it, but a backup costs nothing and the address is irreplaceable. See Backing Up Your Onion Address.

The upgrade

1. Check what changed. Read the release notes / changelog for the new version, especially anything under "Security" or "Changed." Occasionally a new version changes a default worth knowing about.

2. Pull the new image and verify it. Don't skip verification just because it's an upgrade. See Verifying the Image.

docker pull sambent.dev/sam/hiddenforge:2.0.3

3. Update the tag in your docker-compose.yml if you pin a specific version (recommended over latest, so upgrades are a deliberate choice).

4. Recreate the container:

docker compose up -d

Your key folder is a mounted volume, so the new container starts with the same keys and serves the same address. You should see the same .onion when you check:

docker compose exec tor cat /var/lib/tor/hidden_service/mysite/hostname

5. Give it a couple of minutes to bootstrap and republish, then confirm the address loads in Tor Browser.

Why your address survives

On every start, HiddenForge creates the service folder only if it's missing and leaves any existing key exactly as it found it. It never regenerates or overwrites a key. So a new image with a newer Tor version reuses the key you already have. This is tested as part of each release: an in-place upgrade from the previous version keeps the same address.

One thing to know about backends

HiddenForge looks up your backend's address once, at startup. If you upgrade or recreate your backend and it comes up with a different internal IP, HiddenForge won't notice until it restarts too. If your site stops reaching the backend after you rebuild the backend, just recreate the tor container as well:

docker compose up -d

That re-runs the lookup and picks up the backend's new address. Your .onion doesn't change.

Rolling back

If a new version misbehaves, roll back by setting the image tag to the previous version and running docker compose up -d again. Because your keys are untouched, the older version comes back with the same address. This is another reason to pin an explicit version rather than latest: you always have a known-good tag to return to.