Overview
Runs Vaultwarden, a server for the Bitwarden password manager apps, browser extensions and web vault. The block is a singleton that runs where its volume's primary is, behind a VIP. Everything Vaultwarden keeps lives on the volume: the SQLite database, the RSA key that signs login tokens, attachments, Sends and settings saved from the admin page. Vaults are encrypted on each client with the user's master password; the server never sees it.
pkgs.vaultwarden.webvault is needed only for the web vault. Without it, the block serves only the API that apps and extensions use, and logs that it is serving the API only.
- Shape
- Singleton on a replicated volume
- Reached at
- VIP on HTTP
- Node package
pkgs.vaultwardenandpkgs.vaultwarden.webvault
Fetched on demand: the first time a block of this type is placed on a node, its agent fetches pkgs.vaultwarden and pkgs.vaultwarden.webvault, built from the node's own nixpkgs so the NixOS binary cache serves it. That first placement needs network access (or a binary cache on the LAN) and waits for the download; later placements on that node start at once.
Example
apiVersion: expanse.io/v1 kind: Block metadata: name: vault namespace: default spec: type: security/vaultwarden replicas: 1 strategy: kind: SINGLETON resources: requests: cpu: 200m memory: 128Mi storage: - name: vaultwarden-data size: 2Gi replication: 3 mountPath: /var/lib/vaultwarden config: domain: https://vault.example.com signupsAllowed: true adminToken: $argon2id$v=19$m=65540,t=3,p=4$... network: ports: - name: http port: 80 target_port: 18000 protocol: tcp expose: EXPOSE_VIP health_check: readiness: type: PROBE_TCP port: 18000 period_seconds: 2
$ expanse ctl block apply -f vaultwarden.yaml --dry-run # validate only $ expanse ctl block apply -f vaultwarden.yaml
Configuration
Keys go under spec.config and are checked against the type's JSON Schema when the block is applied. A default is what the block uses when the key is unset.
| Key | Default | Meaning |
|---|---|---|
domain | required | URL users and Bitwarden clients reach Vaultwarden at, such as https://vault.example.com; emails and links are built from it. |
signupsAllowed | false | Let anyone who reaches Vaultwarden create an account. |
adminToken | none | Turns on the /admin page. Use the Argon2 string vaultwarden hash prints; a plain token works but Vaultwarden logs it as insecure. Sealed: kept out of the stored block (block secrets). |
port | 18000 | Vaultwarden's HTTP port, the target_port of 80. |
settings | none | Extra Vaultwarden environment variables (upper-case names, one-line values), applied after the block's own. |
Using it
Browsers open the web vault only over HTTPS, because it needs the Web Crypto API. Put a web/caddy block in front, point vault.example.com at Caddy's VIP, have Caddy proxy to this block's VIP (expanse ctl block get vault), and set domain to the https:// address. Plain HTTP reaches only the API, and sends every login over the network unencrypted.
Open sign-ups long enough to create your accounts, then set signupsAllowed: false and re-apply. settings takes any variable from Vaultwarden's .env.template, such as a mail server for invitations, or sign-ups open to one email domain only:
settings: SIGNUPS_DOMAINS_WHITELIST: example.com SMTP_HOST: smtp.example.com SMTP_FROM: vault@example.com SMTP_PORT: 587 SMTP_SECURITY: starttls
The block sets DATA_FOLDER to the volume and DATABASE_CONN_INIT to make SQLite sync every commit. settings can override either, but then a failover may lose data. Settings saved from the admin page are kept in config.json on the volume and take precedence over the manifest. Vaultwarden is built with SQLite only, so DATABASE_URL cannot point at a db/postgres or db/mariadb block.
When a node fails
When the serving node dies, the block, its volume's primary and its VIP move together to a survivor, and Vaultwarden starts there on the same volume. Requests in flight fail; the address stays the same, and logged-in apps stay logged in, because their tokens are signed with the key on the volume.
Nothing Vaultwarden acknowledged is lost. Vaultwarden on its own opens SQLite with synchronous=NORMAL, under which a crash can lose a committed change; the block replaces that with synchronous=FULL, and the volume replicates each write before it completes. Attachments, Sends and config.json are flushed every 2 seconds. In Expanse's three-node VM test, a client saved 20 items and the serving node was killed as soon as the last was acknowledged; a survivor took over 54 to 65 seconds later with all 20 items, and the login token issued before the crash still worked.
Limits
- One Vaultwarden at a time: it keeps its state in SQLite on one volume.
- No HTTPS inside the block; use
web/caddyin front. - Push notifications to mobile apps need an installation ID from Bitwarden (
PUSH_*insettings) and are not tested. - Backups are separate: back up the volume with
util/restic-backup.
Source
- docs/VAULTWARDEN.md: the Expanse guide this page follows.
- nix/blocks/security/vaultwarden: the type's identity and JSON Schema.