nixos-vps/docs/superpowers/specs/2026-03-18-vaultwarden-design.md

Vaultwarden Module Design

Overview

Add Vaultwarden (a lightweight Bitwarden-compatible password manager) as a NixOS module following the existing Podman container pattern.

Requirements

• Domain: vault.ashisgreat.xyz
• WebSocket support for real-time sync
• Admin panel enabled
• No email functionality needed

Module Options

myModules.vaultwarden = {
  enable = lib.mkEnableOption "Vaultwarden password manager";

  domain = lib.mkOption {
    type = lib.types.str;
    example = "vault.example.com";
    description = "Public domain for Vaultwarden";
  };

  port = lib.mkOption {
    type = lib.types.port;
    default = 8222;
    description = "HTTP port for Vaultwarden web interface";
  };

  websocketPort = lib.mkOption {
    type = lib.types.port;
    default = 3012;
    description = "WebSocket port for real-time sync";
  };
};

Architecture

Container Configuration

• Image: vaultwarden/server:latest
• Ports:
  • HTTP: 127.0.0.1:8222 → 80
  • WebSocket: 127.0.0.1:3012 → 3012
• Volumes:
  • vaultwarden-data:/data - Persistent storage for SQLite database
• Environment:
  • ADMIN_TOKEN - From SOPS secret
  • SHOW_PASSWORD_HINT=false - Disabled since no email
  • SIGNUPS_ALLOWED=true - Can be changed via admin panel

Nginx Integration

The module adds the domain to myModules.nginx.domains with:

• Main location / → proxy to HTTP port
• WebSocket location /notifications/hub → proxy to WebSocket port with upgrade headers

Secrets

One secret required in secrets/secrets.yaml:

• vaultwarden_admin_token - Token for accessing the admin panel at /admin

SOPS template vaultwarden.env will inject the admin token.

Files to Create/Modify

File	Action
modules/vaultwarden.nix	Create - new module
modules/default.nix	Modify - add import
configuration.nix	Modify - enable module and add secrets
secrets/secrets.yaml	Modify - add admin token (manual)

Usage

After deployment:

1. Navigate to https://vault.ashisgreat.xyz
2. Create an account
3. Access admin panel at https://vault.ashisgreat.xyz/admin with the admin token

Dependencies

• myModules.podman - Container runtime
• myModules.nginx - Reverse proxy (for domain registration)
• SOPS-nix - Secrets management