How to migrate vaultwarden to a new FQDN?

[cosmadora]

Hi all ^-^

Happy user of vaultwarden for years now. Now i want to migrate to another FQDN without interrupting service for my family.

I had several ideas:

• HTTP 301/308 redirect from vault.example1.com -> vault.example2.com
• configure both FQDNs on Reverse Proxy & Vaultwarden. However, I didn't see in the docs if I can configure two DOMAINs somehow, and I guess leaving DOMAIN to only one fqdn could lead to problems down the line, as stated in the docs.
• ..?

then migrate the clients one by one.

Has anyone already done such a migration? How did it work for you? Is there any best practise?

I've looked through the docs and havent found anything so far.

Thanks in advance!
~Adora

[ssmurfgg04-gif]

Did this exact migration a while back with the same goal of not breaking the family's logins mid week. What worked for us:

1. Vaultwarden only takes one DOMAIN, so set it to the new FQDN and restart. Do this before you hand out the new URL to anyone.
2. Keep the old hostname on the reverse proxy as a second vhost that redirects to the new one. That covers browser bookmarks and the web vault links floating around in emails.
3. The clients are the part that needs manual work. Every app and extension stores the full server URL locally and they do not follow redirects for API calls reliably. Each person just edits the server URL in their client settings, the vault data itself never moves so nothing is re-synced or lost.
4. Check the websocket route for notifications on the new vhost before you flip. If it is missing, clients log in fine but sync quietly stalls until you fix it.

Done that way the switch is zero downtime. Old clients keep working through the redirect for the web vault and each device migrates in under a minute whenever that person gets to it. Once everyone is moved, drop the old vhost.

[AsifMahsud]

Vaultwarden takes exactly one DOMAIN, and the reason it matters for a migration is not only the links in emails. Two things are bound to it:

1. WebAuthn two-step login. src/api/core/two_factor/webauthn.rs builds the relying party from CONFIG.domain(): the RP ID is the hostname of DOMAIN and the allowed origin is DOMAIN itself. A security key or passkey registered as a 2FA method while DOMAIN was vault.example1.com will not validate once it is vault.example2.com, and it will not validate through the old hostname either, because the origin check is against the configured domain, not the URL the request arrived on. So anyone using a hardware key or passkey as their second factor has to remove and re-register it after the switch, or you remove their 2FA from /admin and they set it up again. Passkeys and everything else stored inside the vault are ordinary encrypted data and are not affected. The same file also serves the legacy U2F app-id.json from DOMAIN.
2. Every generated URL: invite and verification emails, the web vault links, and the diagnostics "Domain Configuration Check" in /admin, which will flag a mismatch when the page is opened on a hostname other than DOMAIN.

Nothing in the stored data depends on the hostname, so the migration itself is small:

• Put the new hostname on the reverse proxy, point DOMAIN at it, restart. If you use SSO or Duo, update the redirect URI or integration hostname on that side at the same time.
• Keep the old hostname on the proxy as a redirect for browsers and bookmarks. Do not expect the apps and extensions to follow it: each client stores the full server URL and every family member changes it once in the client's self-hosted settings, then logs in again. Their vault data re-syncs; nothing is lost.
• Warn the people who use a security key or passkey for 2FA before the switch, or have them add a second method such as an authenticator app first, otherwise they lock themselves out on the new domain.

Running two DOMAIN values is not possible, and serving both hostnames without a redirect only works for clients that do not use WebAuthn 2FA, so a short cut-over with the redirect in place is the cleanest path.