Update, back up and move your own relay to a new server

What it is for

Depending on how it was installed, your own relay does not update itself, and its data belongs in a backup. This page shows how to update it for each installation way, how the backup works in the console, how to restore it, and what matters when you move to another server.

What you need

• Your own relay (B2) and a console account as system administrator.
• For Docker and Linux: access to the server's command line.

How to do it

Update

In the console: Settings → Relay update → Check for update, then Apply update. Whether the relay updates itself is set in Configuration → Self-update and mirror → Relay self-update. Leave self-update off on Linux installations that you update with the script.

Back up

1. Settings → Maintenance schedule.
2. Under Backup passphrase set a passphrase and Save. Without a passphrase the relay does not back up its keys.
3. Add job → choose Backup (database + images) and set a schedule. Run now tests the job immediately.
4. The backups are listed under Existing backups. Every database backup comes with an encrypted archive of the keys (….nachweise.zip.enc). Download both and keep them outside the server.

Keep the value BD_KEYRING_KEY (with Docker in the .env file) separately and safely, for example in a password manager (B9).

Restore (same server)

1. Settings → Maintenance schedule → Existing backups → row with the database backup (….dump.gz) → Restore.
2. In the dialog Restore database? type the database name and click Restore.
3. The relay restarts. Sign in again afterwards.

Move to a new server

1. Install the relay on the new server the same way (B2), but do not start it yet, or stop it again right away.
2. Decrypt the key archive with the backup passphrase and unpack it into the relay's data folder before the first start: openssl enc -d -aes-256-cbc -pbkdf2 -in <name>.nachweise.zip.enc -out nachweise.zip
3. If BD_KEYRING_KEY was set, set the same value on the new server before the relay starts.
4. Start the relay, then restore the database backup (as above).
5. Point the name (DNS) at the new server. If the devices keep the same address, you do not need to change anything on them. For a new address: C6.
6. Licence: a licence is valid for one installation. Have the activation released at browserdesk.de (info@browserdesk.de) and install the licence file again on the new server (A5).

How you know it worked

• After an update, Relay status (or /health) shows the new version.
• After restoring, the console confirms that the database was restored, names the file holding the previous state, and says that the relay is restarting.
• After a move the devices sign in at the new server, and their device certificates remain valid.

Good to know

• Running sessions during an update: the viewer shows „Relay wird aktualisiert – Verbindung wird wiederhergestellt …“ (relay is being updated, reconnecting) and reconnects by itself. A direct session keeps running.
• Restoring resets everything: devices, accesses, users, tickets, settings. Whatever came later is gone. The state before lies as …-vor-einspielen.dump.gz in the same list — that is how you undo it.
• All console sign-ins end when restoring.
• Without the keys, all encrypted values are empty on a new server: a new device CA (all device certificates invalid), mail and sign-in credentials gone.
• Windows wraps the keys to the machine (without BD_KEYRING_KEY). A move to another machine is then not possible without losing the encrypted values; there is no way to re-wrap yet. Write to info@browserdesk.de before such a move.
• Linux without BD_KEYRING_KEY stores the keys unencrypted and warns at start-up (B9).
• Docker: the whole backup is the data/ folder plus the value BD_KEYRING_KEY from .env.
• Going back to the old version with Docker: set RELAY_VERSION in .env back and run docker compose up -d, as long as the old image is still loaded.

If it does not work