7 min to read

Understanding and Installing Vaultwarden - A Self-Hosted Password Manager

A comprehensive guide to Vaultwarden deployment on Kubernetes

Featured image

Image Reference link


Introduction to Vaultwarden

Vaultwarden is a lightweight, open-source alternative to the official Bitwarden server implementation. Written in Rust instead of .NET, it offers significantly reduced resource requirements while maintaining compatibility with all official Bitwarden clients, making it ideal for self-hosting password management solutions for individuals and small teams.


What is Vaultwarden?

The Self-Hosted Password Management Solution

Vaultwarden (formerly known as Bitwarden_RS) provides a self-contained, efficient implementation of the Bitwarden API that enables:

  • Full Control: Complete ownership of your sensitive password data
  • Privacy: No reliance on Bitwarden's cloud infrastructure
  • Simplicity: Simplified deployment with minimal resource consumption
  • Compatibility: Works with all official Bitwarden clients and browser extensions

While retaining core functionality, Vaultwarden consumes a fraction of the resources needed by the official Bitwarden server, making it accessible for home labs and small environments.

graph LR A[Vaultwarden] --> B[Secure Password Storage] A --> C[Client Compatibility] A --> D[Resource Efficiency] A --> E[Self-Hosting Features] B --> B1[AES-256 Encryption] B --> B2[Zero-Knowledge Model] C --> C1[Browser Extensions] C --> C2[Mobile Apps] C --> C3[Desktop Clients] D --> D1[Low Memory Footprint] D --> D2[Single Binary] D --> D3[SQLite Support] E --> E1[Custom Configuration] E --> E2[Backups Control] E --> E3[Custom Domain] style A stroke:#333,stroke-width:1px,fill:#f5f5f5 style B stroke:#333,stroke-width:1px,fill:#a5d6a7 style C stroke:#333,stroke-width:1px,fill:#64b5f6 style D stroke:#333,stroke-width:1px,fill:#ffcc80 style E stroke:#333,stroke-width:1px,fill:#ce93d8


Key Features and Capabilities

Feature Description
Lightweight Architecture
  • Written in Rust for performance and security
  • Minimal RAM requirements (< 10MB idle)
  • Small CPU footprint (suitable for ARM devices)
  • Containerized deployment for easy management
Seamless Compatibility
  • Supports all Bitwarden clients (iOS, Android, desktop)
  • Compatible with browser extensions (Chrome, Firefox, Safari)
  • Directory connector functionality
  • Implements the complete Bitwarden API
Storage Flexibility
  • SQLite database by default (low overhead)
  • Optional MySQL/MariaDB and PostgreSQL support
  • Efficient attachment storage
  • Configurable backup solutions
Security Features
  • Two-factor authentication (2FA)
  • WebAuthn/FIDO2 support
  • Emergency access options
  • Admin console for user management


Vaultwarden vs. Official Bitwarden

Key Differences

While Vaultwarden provides most of the functionality of the official Bitwarden server, there are some important distinctions:

  • Community Support: Relies on community support rather than official Bitwarden support
  • Enterprise Features: Some advanced enterprise features may be limited or unavailable
  • Update Cycle: May lag behind official server updates when API changes occur
  • Licensing: Free for all features, without the license requirements of official Bitwarden

For most personal and small team use cases, these differences are acceptable trade-offs for the simplified deployment and reduced resource requirements.

graph LR subgraph "Vaultwarden" A1[Rust Implementation] A2[Single Container] A3[SQLite Default] A4[Low Resource Usage] end subgraph "Official Bitwarden" B1[.NET Implementation] B2[Microservices Architecture] B3[MS SQL Default] B4[Higher Resource Requirements] end C[Common Features] C --> C1[Password Storage] C --> C2[Client Compatibility] C --> C3[Password Generation] C --> C4[2FA Support] style A1 stroke:#333,stroke-width:1px,fill:#a5d6a7 style A2 stroke:#333,stroke-width:1px,fill:#a5d6a7 style A3 stroke:#333,stroke-width:1px,fill:#a5d6a7 style A4 stroke:#333,stroke-width:1px,fill:#a5d6a7 style B1 stroke:#333,stroke-width:1px,fill:#64b5f6 style B2 stroke:#333,stroke-width:1px,fill:#64b5f6 style B3 stroke:#333,stroke-width:1px,fill:#64b5f6 style B4 stroke:#333,stroke-width:1px,fill:#64b5f6 style C stroke:#333,stroke-width:1px,fill:#f5f5f5


Deployment on Kubernetes using Helm

Deploying Vaultwarden on Kubernetes provides the benefits of container orchestration, including scaling, automated recovery, and simplified updates. The Helm chart approach streamlines the installation process and provides a consistent deployment method.

Prerequisites

Before You Begin

To successfully deploy Vaultwarden on Kubernetes, ensure you have:

  • Kubernetes Cluster: A working Kubernetes cluster (can be local like Minikube or Kind)
  • Helm: Helm 3 installed and configured to work with your cluster
  • Storage: A default StorageClass configured for persistent volume claims
  • Ingress Controller: NGINX Ingress or similar for external access
  • DNS: A domain name pointing to your Kubernetes ingress (for production use)

Preparation Steps

1. Setting Up the Helm Repository

# Clone charts repository
git clone https://github.com/gissilabs/charts.git

# Add Helm repository
helm repo add gissilabs https://gissilabs.github.io/charts/

# Prepare values file
cd ~/charts/vaultwarden
mkdir values
cp values.yaml values/mgmt.yaml
sequenceDiagram participant User participant Helm participant K8s as Kubernetes User->>Helm: Add repository User->>Helm: Create values file User->>Helm: Install chart Helm->>K8s: Create deployment Helm->>K8s: Create service Helm->>K8s: Create ingress K8s->>K8s: Provision storage K8s-->>User: Deployment complete

2. Configuring Backup Templates

Data Protection

Setting up proper backup procedures is critical for password managers. The following templates create a CronJob that regularly backs up your Vaultwarden data:

Create templates/backup-cronjob.yaml:

Create templates/backup-persistentvolumeclaim.yaml:


Configuration Options

Configuration Area Available Options
Database
  • type: SQLite (default), MySQL/MariaDB, or PostgreSQL
  • wal: Write-ahead logging for improved performance
  • connection: Connection string for external databases
Security
  • verifySignup: Enable/disable email verification for new accounts
  • invitationsAllowed: Control organization invitations
  • admin.enabled: Enable admin interface
  • admin.token: Set administrative access token
Networking
  • service.type: ClusterIP, NodePort, or LoadBalancer
  • ingress.enabled: Enable ingress for external access
  • ingress.host: Hostname for accessing Vaultwarden
  • ingress.annotations: Custom ingress controller settings
Storage
  • persistence.enabled: Enable persistent storage
  • persistence.size: Storage size allocation
  • persistence.storageClass: Kubernetes storage class to use
  • persistence.existingClaim: Use existing PVC

Example Configuration File

database:
  type: sqlite
  wal: true

vaultwarden:
  verifySignup: false
  admin:
    enabled: true
    disableAdminToken: false
    token: "Somaz!123"
  
  emergency:
    enabled: true

service:
  type: ClusterIP
  httpPort: 80

ingress:
  enabled: true
  className: "nginx"
  host: "vaultwarden.somaz.link"
  annotations:
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"

persistence:
  enabled: true
  size: 25Gi
  storageClass: "default"


Deployment Process

Step-by-Step Deployment

Follow these steps to deploy Vaultwarden to your Kubernetes cluster:



Advanced Configuration

Email Notification Setup (SMTP)

Communication Features

Configuring SMTP allows Vaultwarden to send important notifications:

  • Account verification emails
  • Password hint reminders
  • Organization invitations
  • Emergency access requests

Add to your values file:

smtp:
  enabled: true
  host: "smtp.office365.com"
  from: "noreply@somaz.link"
  fromName: "Somaz, Inc."
  security: starttls
  port: 587
  timeout: 15
  user: ""
  password: ""

Maintenance and Upgrades

graph LR A[Check Updates] --> B[Back Up Data] B --> C[Update Values File] C --> D[Run Upgrade Command] D --> E[Verify Functionality] style A stroke:#333,stroke-width:1px,fill:#a5d6a7 style B stroke:#333,stroke-width:1px,fill:#a5d6a7 style C stroke:#333,stroke-width:1px,fill:#a5d6a7 style D stroke:#333,stroke-width:1px,fill:#a5d6a7 style E stroke:#333,stroke-width:1px,fill:#a5d6a7

To upgrade your installation:

# Update the Helm repository
helm repo update

# Apply the upgrade
helm upgrade vaultwarden . -n vaultwarden -f ./values/mgmt.yaml


Post-Installation

💡 Accessing Your Vaultwarden Instance
  • Web Interface
    - Access your Vaultwarden instance at your configured domain
    - Create your master account and set up your organization structure
    - Use the admin panel for system configuration (https://your-domain.com/admin)
  • Client Setup
    - Install Bitwarden clients on your devices
    - Configure the client to use your self-hosted URL
    - Login with your master credentials
  • Security Best Practices
    - Use a strong, unique master password
    - Enable two-factor authentication
    - Configure regular data backups
    - Keep your Vaultwarden instance updated

vaultwarden-console


References