Vaultwarden

​

Overview

​

Architecture

• Vaultwarden — A single-replica stateful workload serving the web vault, APIs, and websocket live-sync on port 80. Its public DOMAIN is derived from the canonical endpoint at boot, so clients and passkeys bind to the correct URL with no manual configuration.
• SQLite on a persistent volume — All state (accounts, vault items, attachments, sends, and the RSA key that signs login sessions) lives in a SQLite database on the workload’s volume set; there is no external database dependency.

​

What Gets Created

• Stateful Vaultwarden Workload — A single replica serving the web vault, APIs, and websocket notifications on port 80.
• Volume Set — A 10 GiB persistent volume mounted at /data holding the SQLite database, attachments, sends, and RSA signing keys. Scheduled snapshots protect the data, and a final snapshot is kept on delete.
• Start-Script Secret — An opaque secret whose boot script sets DOMAIN from the canonical endpoint.
• Identity & Policy — An identity bound to the workload with a least-privilege policy granting reveal access to exactly the secrets it mounts (the start script, plus your admin and SMTP secrets only when you configure them).

​

Prerequisites

• Admin panel (/admin) — Create, before installing, an opaque secret (encoding: plain) holding the argon2 hash of your admin token. Generate the hash with docker run --rm -it vaultwarden/server:1.36.0 /vaultwarden hash and store the full $argon2... output as-is — do not double the $ signs (that is docker-compose escaping and will break login here). Set the secret’s name in admin.tokenSecretName.
• Authenticated SMTP — Create a dictionary secret with exactly two keys, username and password, for your mail server, and set its name in smtp.authSecretName. Only needed when your relay requires authentication.

​

Configuration

image: vaultwarden/server:1.36.0

resources:
  cpu: 500m
  memory: 512Mi
  minCpu: 125m
  minMemory: 256Mi

volumeset:
  capacity: 10 # GiB (minimum 10) — SQLite database, attachments, sends, and RSA keys

# ─── Backup ───────────────────────────────────────────────────────────────────
# Scheduled, crash-consistent snapshots of the data volume, managed by the
# platform (no cloud account or bucket required). SQLite recovers cleanly from a
# snapshot via its WAL. A final snapshot is always taken on uninstall.
backup:
  enabled: true # periodic snapshots of the data volume
  schedule: "0 3 * * *" # cron in UTC — default daily at 03:00 (hourly is the most frequent the platform allows)
  retention: 7d # how long each snapshot is kept (e.g. 7d, 720h, 30d)

# ─── Sign-ups & Invitations ───────────────────────────────────────────────────
# Registration is OPEN by default so a fresh install is immediately usable.
# After onboarding your users, lock down: set allowed=false or restrict
# registration with domainsWhitelist.
signups:
  allowed: true # open registration on the public endpoint — turn off after onboarding
  domainsWhitelist: [] # email domains that may register even when allowed=false, e.g. [mycompany.com]
  verify: false # require email verification at registration (needs smtp.host)

invitations:
  allowed: true # existing org owners can invite users; invited emails may register

# ─── Admin Panel (/admin — disabled by default) ───────────────────────────────
# To enable, create BEFORE install an opaque secret (encoding: plain) holding
# the argon2 hash of your admin token:
#   docker run --rm -it vaultwarden/server:1.36.0 /vaultwarden hash
admin:
  tokenSecretName: "" # name of your pre-created opaque secret (e.g. my-vaultwarden-admin-token); empty = /admin disabled

# ─── SMTP (optional — invites, verification, 2FA email) ───────────────────────
smtp:
  host: "" # e.g. smtp.example.com; empty = all email features off
  port: 587
  security: starttls # options: starttls, force_tls, off
  from: "" # sender address (required when host is set)
  authSecretName: "" # pre-created dictionary secret with keys `username` and `password` (e.g. my-vaultwarden-smtp-auth); empty = unauthenticated relay

# ─── Privacy ──────────────────────────────────────────────────────────────────
icons:
  disableDownload: false # set true to stop the server fetching site favicons (outbound requests reveal stored-site domains); clients then show letter placeholders

customDomain: "" # full URL of a custom domain (e.g. https://vault.example.com); empty = canonical *.cpln.app endpoint

# ─── Access ───────────────────────────────────────────────────────────────────
publicAccess:
  enabled: true # Bitwarden clients (browser/desktop/mobile) connect via the canonical *.cpln.app HTTPS endpoint

internalAccess: # internal firewall scope — keep closed for a password vault unless in-GVC callers need the API
  type: none # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list

​

Vaultwarden Instance

• image — The Vaultwarden container image.
• resources — CPU and memory for the Vaultwarden container.
• volumeset.capacity — Volume size in GiB (minimum 10) for the SQLite database, attachments, sends, and RSA keys.

​

Backup

• backup.enabled — Take periodic snapshots of the data volume (default true).
• backup.schedule — Cron expression in UTC (default 0 3 * * *, daily at 03:00). The platform does not accept schedules more frequent than hourly.
• backup.retention — How long each snapshot is kept, e.g. 7d, 720h, 30d.

​

Sign-ups & Invitations

• signups.allowed — Open registration on the public endpoint (default true so a fresh install is usable). Turn this off after onboarding — see Important Notes.
• signups.domainsWhitelist — Email domains that may register even when signups.allowed is false, e.g. [mycompany.com]. This also gates who can be invited.
• signups.verify — Require email verification at registration. Requires smtp.host.
• invitations.allowed — Allow existing organization owners to invite users; invited emails may then register.

​

Admin Panel

• admin.tokenSecretName — Name of a pre-created opaque secret holding the argon2 hash of your admin token (see Prerequisites). Empty (default) leaves the /admin panel disabled.

​

SMTP

• smtp.host — Mail server hostname. Empty (default) disables all email features.
• smtp.port — SMTP port (default 587).
• smtp.security — starttls, force_tls, or off.
• smtp.from — Sender address; required when smtp.host is set.
• smtp.authSecretName — Name of a pre-created dictionary secret with username and password keys (see Prerequisites). Empty means an unauthenticated relay.

​

Privacy

• icons.disableDownload — Set to true to stop the server fetching site favicons. Those outbound requests reveal which sites users store; with downloads off, clients show letter placeholders instead.

​

Domain

• customDomain — Full URL of a custom domain, e.g. https://vault.example.com. Empty (default) uses the canonical *.cpln.app endpoint. See the domain caution in Important Notes before changing this on a live vault.

​

Access

• publicAccess.enabled — Serve Vaultwarden over HTTPS on the canonical *.cpln.app endpoint (default). Bitwarden clients require HTTPS, so keep this enabled unless you front the vault another way. When disabled, external requests are blocked at the edge and only in-GVC callers reach it per internalAccess.
• internalAccess.type — Internal firewall scope of the Vaultwarden workload. Keep this closed (none, the default) for a password vault unless in-GVC callers need the API:

​

Connecting

​

Clients and Live Sync

​

Backing Up

• Default schedule — Daily at 03:00 UTC (backup.schedule: "0 3 * * *"), kept for 7 days (backup.retention: 7d).
• Minimum interval — The platform does not accept schedules more frequent than hourly.

cpln volumeset snapshot get {release}-vaultwarden-data --gvc {gvc} -o yaml

​

Restoring a Backup

cpln volumeset snapshot get {release}-vaultwarden-data --gvc {gvc} -o yaml

cpln volumeset snapshot restore {release}-vaultwarden-data \
  --snapshot-name <snapshot-name> \
  --location <location> \
  --volume-index 0 \
  --gvc {gvc}

​

Important Notes

• Lock down registration after onboarding. Sign-ups are open by default so the install works immediately — which means anyone who can reach the public endpoint can register. Once your users are on board, set signups.allowed=false, or restrict with signups.domainsWhitelist (whitelisted domains can still register with sign-ups off).
• Vault contents are end-to-end encrypted with each user’s master password, and master passwords are unrecoverable. Without SMTP configured, password-hint emails are off, so a forgotten master password means a lost vault.
• Admin panel settings override Helm values. Saving settings in /admin writes /data/config.json, which silently wins over environment variables from then on. If a values change does not take effect, delete that file to return control to values.
• Store the admin token hash raw. Put the argon2 output (starting with $argon2) into the secret as-is — do not double the $ signs; that escaping is for docker-compose only and breaks login here.
• Do not change the domain casually. Passkey/WebAuthn logins are bound to the exact URL; switching between the canonical endpoint and a custom domain breaks them until re-registered.
• Single instance only — upstream does not support running multiple instances, so the workload is pinned to 1 replica with no replicas knob. A restart is a short full outage (about a minute); Bitwarden apps keep a local offline copy of the vault, so users can still read their vault during it.
• Backups are in-platform, not off-site — scheduled snapshots and the final snapshot on uninstall live in the platform storage layer next to the volume; losing the whole GVC would lose them too. See Backing Up.

​

External References