# Vaultwarden Password Management

* Status: accepted
* Date: 2026-02-09
* Deciders: Billy
* Technical Story: Self-host a Bitwarden-compatible password manager for personal and family credential management

## Context and Problem Statement

Password management is essential for security, and commercial Bitwarden plans charge per-user fees for family/team features. Vaultwarden provides a lightweight, Bitwarden-compatible server that runs all premium features without licensing costs.

How do we self-host password management with the reliability and accessibility requirements of a critical personal service?

## Decision Drivers

* Bitwarden client compatibility (browser extensions, mobile apps, CLI)
* All premium features (TOTP, file attachments, organizations) without licensing
* High availability relative to importance (password manager is critical infrastructure)
* Public access for mobile/remote use
* Minimal attack surface

## Considered Options

1. **Vaultwarden** — Rust reimplementation of Bitwarden server API
2. **Bitwarden (official)** — Official self-hosted Bitwarden
3. **KeePass/KeePassXC** — File-based password manager with sync
4. **1Password** — Commercial SaaS

## Decision Outcome

Chosen option: **Vaultwarden**, because it provides full Bitwarden client compatibility in a single lightweight container, supports all premium features, and uses PostgreSQL for reliable storage.

### Positive Consequences

* All Bitwarden clients work natively (browser, mobile, desktop, CLI)
* All premium features unlocked (TOTP, attachments, emergency access, organizations)
* Single container (~50MB RAM) instead of Bitwarden's 6+ containers
* PostgreSQL backend via CNPG for reliable, backed-up storage
* Existing Bitwarden vaults can be migrated via import

### Negative Consequences

* Third-party reimplementation — may lag behind official Bitwarden features
* Self-hosted means self-responsible for backups and availability
* Public-facing service increases attack surface

## Deployment Configuration

| | |
|---|---|
| **Image** | `vaultwarden/server:1.35.2` |
| **Namespace** | `productivity` |
| **Chart** | bjw-s `app-template` |
| **Signups** | Disabled (`SIGNUPS_ALLOWED=false`) |
| **Admin panel** | Disabled |
| **Storage** | 10Gi Longhorn PVC (attachments/icons) |

### Database

PostgreSQL via **CloudNativePG**:
- 1 instance, `amd64` node affinity
- 10Gi Longhorn storage
- Credentials from Vault via ExternalSecret

### Network Access

| | |
|---|---|
| **Gateway** | `envoy-external` |
| **URL** | `vaultwarden.daviestechlabs.io` |
| **TLS** | Let's Encrypt wildcard (DNS-01 via Cloudflare) |

Publicly accessible via Cloudflare Tunnel so mobile apps and browser extensions work from anywhere.

## Security Hardening

* New user signups disabled — accounts provisioned manually
* Admin panel disabled — reduces attack surface
* Vault credentials from HashiCorp Vault (not inline)
* WebSocket support for real-time sync between clients
* All Bitwarden data encrypted client-side (server never sees plaintext)

Vaultwarden serves only encrypted blobs. The encryption key never leaves the client, so even a full server compromise does not expose plaintext passwords.

## Links

* Related to [ADR-0027](0027-database-strategy.md) (CNPG PostgreSQL)
* Related to [ADR-0044](0044-dns-and-external-access.md) (Cloudflare Tunnel access)
* Related to [ADR-0045](0045-tls-certificate-strategy.md) (Let's Encrypt TLS)
* [Vaultwarden](https://github.com/dani-garcia/vaultwarden)