97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# Vaultwarden
|
|
|
|
Self-hosted password manager — a lightweight, Rust-based implementation of the Bitwarden server API, giving full Bitwarden client compatibility (browser extensions, mobile apps, desktop apps) without Bitwarden's cloud dependency.
|
|
|
|
See [docker-compose/vaultwarden/](../docker-compose/vaultwarden/) for the deployment files.
|
|
|
|
## Why
|
|
|
|
After years of managing passwords across various tools, a self-hosted password manager was the missing piece. Vaultwarden provides:
|
|
|
|
- **Full Bitwarden compatibility** — works with the official Bitwarden browser extension, iOS/Android apps, and desktop apps. No proprietary client lock-in.
|
|
- **Lightweight** — single container, SQLite database, minimal resource usage. Runs comfortably alongside the rest of the stack.
|
|
- **Local data ownership** — passwords never leave the LAN unless you want them to (via Bitwarden's sync protocol for mobile access outside the home).
|
|
- **Long passwords** — using Vaultwarden as the source of truth for 30+ character passwords across all services, replacing the short memorable passwords that were previously hardcoded in compose files.
|
|
|
|
## Setup
|
|
|
|
### Initial configuration
|
|
|
|
```bash
|
|
cd docker-compose/vaultwarden
|
|
docker compose up -d
|
|
```
|
|
|
|
Access the web UI at `vaultwarden.home.server` (via Traefik) or `http://localhost:8084` directly.
|
|
|
|
**First step:** create your admin account, then set `SIGNUPS_ALLOWED=false` in the compose file to prevent new registrations.
|
|
|
|
### Generating password hashes
|
|
|
|
Vaultwarden uses the same `admin_token` mechanism as Bitwarden for admin access. For the Traefik basicAuth middleware (DockScope), generate hashes with:
|
|
|
|
```bash
|
|
htpasswd -nB <username>
|
|
```
|
|
|
|
This produces bcrypt-hashed entries compatible with Traefik's basicAuth middleware.
|
|
|
|
## Integration with the homelab
|
|
|
|
### Traefik routing
|
|
|
|
Vaultwarden is fronted by Traefik with the standard label set:
|
|
|
|
- `vaultwarden.home.server` → HTTPS → container port 80
|
|
- HTTP → HTTPS redirect
|
|
- Security headers middleware
|
|
|
|
### Password management workflow
|
|
|
|
1. Store all service passwords in Vaultwarden (30+ character randomly generated)
|
|
2. Reference passwords via `.env` files on the host (not in compose files)
|
|
3. Compose files use `${VARIABLE}` references, never hardcoded values
|
|
|
|
This is the migration path from the previous approach of short, memorable passwords hardcoded in compose files — the Traefik migration was the catalyst for adopting proper secret management across the stack.
|
|
|
|
## Configuration
|
|
|
|
Key environment variables in `docker-compose.yml`:
|
|
|
|
| Variable | Value | Purpose |
|
|
|---|---|---|
|
|
| `WEBSOCKET_ENABLED` | `true` | Enable real-time sync with Bitwarden clients |
|
|
| `SIGNUPS_ALLOWED` | `false` | Disable new account creation after initial setup |
|
|
|
|
Data is stored in `./vw-data/` (gitignored).
|
|
|
|
## Security notes
|
|
|
|
- Signups are disabled after initial account creation
|
|
- The web UI is only accessible via HTTPS through Traefik (LAN-only via Pi-hole DNS)
|
|
- Vaultwarden encrypts all vault data client-side before transmission — even if the server is compromised, passwords remain encrypted
|
|
- The `vw-data/` directory contains the SQLite database and should be backed up regularly
|
|
- Admin panel is accessible at `vaultwarden.home.server/admin` (requires admin token)
|
|
|
|
## Backups
|
|
|
|
The SQLite database in `vw-data/` should be backed up as part of the regular backup strategy. A simple approach:
|
|
|
|
```bash
|
|
# stop the container, copy the data, restart
|
|
docker compose stop vaultwarden
|
|
cp -r vw-data/ /backups/vaultwarden-$(date +%Y%m%d)/
|
|
docker compose start vaultwarden
|
|
```
|
|
|
|
Or use the Bitwarden CLI to export a JSON/CSV backup from within the web UI.
|
|
|
|
## Lessons learned
|
|
|
|
- Migrating from hardcoded passwords to a password manager is painful but worth it — the Traefik migration forced the cleanup, and now every service uses proper secret references.
|
|
- 30+ character passwords are free with a password manager — there's no reason to use short, memorable passwords for services that only need them in `.env` files.
|
|
- Vaultwarden's Bitwarden compatibility means you don't have to convince family members to use a different app — the official Bitwarden clients just work.
|
|
- The `SIGNUPS_ALLOWED` flag is easy to forget — leave it `true` too long and anyone on the LAN can create an account.
|
|
|
|
[← Back to Home](Home.md)
|