docs: update Vaultwarden plan with nginx extraLocations fix
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
5b584cdb11
commit
a2a0dfaa58
1 changed files with 358 additions and 0 deletions
358
docs/superpowers/plans/2026-03-18-vaultwarden.md
Normal file
358
docs/superpowers/plans/2026-03-18-vaultwarden.md
Normal file
|
|
@ -0,0 +1,358 @@
|
|||
# Vaultwarden Module Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Add Vaultwarden password manager as a NixOS module with Podman container, Nginx reverse proxy, and SOPS secrets.
|
||||
|
||||
**Architecture:** Podman container running vaultwarden/server image with HTTP and WebSocket ports, integrated with existing Nginx module for reverse proxy and TLS, using SOPS for admin token secret management.
|
||||
|
||||
**Tech Stack:** NixOS, Podman, Nginx, SOPS-nix, Vaultwarden
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `modules/nginx.nix` | Modify - add `extraLocations` option for WebSocket support |
|
||||
| `modules/vaultwarden.nix` | New module - defines options and container config |
|
||||
| `modules/default.nix` | Add import for vaultwarden module |
|
||||
| `configuration.nix` | Enable module, declare SOPS secrets/templates |
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Extend Nginx Module for Extra Locations
|
||||
|
||||
**Files:**
|
||||
- Modify: `modules/nginx.nix`
|
||||
|
||||
- [ ] **Step 1: Add `extraLocations` option to domain submodule**
|
||||
|
||||
Add a new option after `extraConfig` (around line 46):
|
||||
|
||||
```nix
|
||||
extraLocations = lib.mkOption {
|
||||
type = lib.types.attrsOf (lib.types.submodule {
|
||||
options = {
|
||||
proxyPass = lib.mkOption {
|
||||
type = lib.types.str;
|
||||
description = "Proxy target URL";
|
||||
};
|
||||
extraConfig = lib.mkOption {
|
||||
type = lib.types.lines;
|
||||
default = "";
|
||||
description = "Extra Nginx config for this location";
|
||||
};
|
||||
};
|
||||
});
|
||||
default = { };
|
||||
description = "Additional location blocks to add to this virtual host";
|
||||
};
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update virtualHosts generation to include extraLocations**
|
||||
|
||||
Replace the `virtualHosts` block (lines 76-87) with:
|
||||
|
||||
```nix
|
||||
virtualHosts = lib.mapAttrs' (domain: opts: {
|
||||
name = domain;
|
||||
value = {
|
||||
enableACME = true;
|
||||
forceSSL = true;
|
||||
|
||||
locations = {
|
||||
"/" = {
|
||||
proxyPass = "http://127.0.0.1:${toString opts.port}";
|
||||
extraConfig = opts.extraConfig;
|
||||
};
|
||||
} // lib.mapAttrs' (locPath: locOpts: {
|
||||
name = locPath;
|
||||
value = {
|
||||
proxyPass = locOpts.proxyPass;
|
||||
extraConfig = locOpts.extraConfig;
|
||||
};
|
||||
}) opts.extraLocations;
|
||||
};
|
||||
}) cfg.domains;
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Verify syntax**
|
||||
|
||||
Run: `nix-instantiate --parse modules/nginx.nix`
|
||||
Expected: No parse errors
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add modules/nginx.nix
|
||||
git commit -m "feat(nginx): add extraLocations option for WebSocket support
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Create Vaultwarden Module File
|
||||
|
||||
**Files:**
|
||||
- Create: `modules/vaultwarden.nix`
|
||||
|
||||
- [ ] **Step 1: Create module file**
|
||||
|
||||
```nix
|
||||
# Vaultwarden Module (Podman)
|
||||
# Provides: Bitwarden-compatible password manager
|
||||
#
|
||||
# Usage:
|
||||
# myModules.vaultwarden = {
|
||||
# enable = true;
|
||||
# port = 8222;
|
||||
# websocketPort = 3012;
|
||||
# domain = "vault.example.com";
|
||||
# };
|
||||
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
pkgs,
|
||||
...
|
||||
}:
|
||||
|
||||
let
|
||||
cfg = config.myModules.vaultwarden;
|
||||
in
|
||||
{
|
||||
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";
|
||||
};
|
||||
};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
# Enable podman
|
||||
myModules.podman.enable = true;
|
||||
|
||||
# Vaultwarden container
|
||||
virtualisation.oci-containers.containers."vaultwarden" = {
|
||||
image = "vaultwarden/server:latest";
|
||||
ports = [
|
||||
"127.0.0.1:${toString cfg.port}:80"
|
||||
"127.0.0.1:${toString cfg.websocketPort}:3012"
|
||||
];
|
||||
environmentFiles = [
|
||||
config.sops.templates."vaultwarden.env".path
|
||||
];
|
||||
environment = {
|
||||
SHOW_PASSWORD_HINT = "false";
|
||||
SIGNUPS_ALLOWED = "true";
|
||||
};
|
||||
volumes = [
|
||||
"vaultwarden-data:/data"
|
||||
];
|
||||
};
|
||||
|
||||
# Register with Nginx (using extraLocations for WebSocket)
|
||||
myModules.nginx.domains."${cfg.domain}" = {
|
||||
port = cfg.port;
|
||||
extraLocations."/notifications/hub" = {
|
||||
proxyPass = "http://127.0.0.1:${toString cfg.websocketPort}";
|
||||
extraConfig = ''
|
||||
proxyHttpVersion 1.1;
|
||||
proxySetHeader Upgrade $http_upgrade;
|
||||
proxySetHeader Connection "upgrade";
|
||||
'';
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify file was created**
|
||||
|
||||
Run: `cat modules/vaultwarden.nix | head -20`
|
||||
Expected: Module header and options visible
|
||||
|
||||
- [ ] **Step 3: Commit module file**
|
||||
|
||||
```bash
|
||||
git add modules/vaultwarden.nix
|
||||
git commit -m "feat: add Vaultwarden module (Podman)
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Register Module in default.nix
|
||||
|
||||
**Files:**
|
||||
- Modify: `modules/default.nix`
|
||||
|
||||
- [ ] **Step 1: Add vaultwarden import**
|
||||
|
||||
Edit `modules/default.nix` to add `./vaultwarden.nix` to imports:
|
||||
|
||||
```nix
|
||||
# Module exports
|
||||
{
|
||||
imports = [
|
||||
./system.nix
|
||||
./podman.nix
|
||||
./nginx.nix
|
||||
./searxng.nix
|
||||
./openclaw-podman.nix
|
||||
./vaultwarden.nix
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify syntax**
|
||||
|
||||
Run: `nix-instantiate --parse modules/default.nix`
|
||||
Expected: No parse errors
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add modules/default.nix
|
||||
git commit -m "feat: register Vaultwarden module in default.nix
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Configure Vaultwarden in configuration.nix
|
||||
|
||||
**Files:**
|
||||
- Modify: `configuration.nix`
|
||||
|
||||
- [ ] **Step 1: Add Vaultwarden module configuration**
|
||||
|
||||
Add after the OpenClaw section (around line 95):
|
||||
|
||||
```nix
|
||||
# === Vaultwarden ===
|
||||
myModules.vaultwarden = {
|
||||
enable = true;
|
||||
port = 8222;
|
||||
websocketPort = 3012;
|
||||
domain = "vault.ashisgreat.xyz";
|
||||
};
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Add SOPS secret declaration**
|
||||
|
||||
Add after the OpenClaw secrets (around line 100):
|
||||
|
||||
```nix
|
||||
sops.secrets.vaultwarden_admin_token = { };
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Add SOPS template**
|
||||
|
||||
Add after the openclaw.env template (around line 108):
|
||||
|
||||
```nix
|
||||
sops.templates."vaultwarden.env" = {
|
||||
content = ''
|
||||
ADMIN_TOKEN=${config.sops.placeholder.vaultwarden_admin_token}
|
||||
'';
|
||||
};
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Verify configuration builds**
|
||||
|
||||
Run: `nixos-rebuild build --flake .#nixos`
|
||||
Expected: Build succeeds without errors
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add configuration.nix
|
||||
git commit -m "feat: enable Vaultwarden with secrets configuration
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Add Admin Token Secret (Manual)
|
||||
|
||||
**Files:**
|
||||
- Modify: `secrets/secrets.yaml` (encrypted)
|
||||
|
||||
- [ ] **Step 1: Edit secrets file**
|
||||
|
||||
Run: `nix-shell -p sops --run "sops secrets/secrets.yaml"`
|
||||
|
||||
- [ ] **Step 2: Add vaultwarden_admin_token**
|
||||
|
||||
Add this entry to the YAML file:
|
||||
```yaml
|
||||
vaultwarden_admin_token: "your-secure-admin-token-here"
|
||||
```
|
||||
|
||||
Replace `your-secure-admin-token-here` with a strong password/token.
|
||||
|
||||
- [ ] **Step 3: Save and exit**
|
||||
|
||||
The file will be re-encrypted automatically.
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Deploy and Verify
|
||||
|
||||
- [ ] **Step 1: Deploy configuration**
|
||||
|
||||
Run: `sudo nixos-rebuild switch --flake .#nixos`
|
||||
Expected: Deployment succeeds
|
||||
|
||||
- [ ] **Step 2: Verify container is running**
|
||||
|
||||
Run: `sudo podman ps | grep vaultwarden`
|
||||
Expected: Container listed as running
|
||||
|
||||
- [ ] **Step 3: Verify web interface**
|
||||
|
||||
Run: `curl -I http://127.0.0.1:8222`
|
||||
Expected: HTTP 200 response
|
||||
|
||||
- [ ] **Step 4: Final commit (if any changes)**
|
||||
|
||||
```bash
|
||||
git status
|
||||
# If secrets.yaml was modified (git tracks encrypted version):
|
||||
git add secrets/secrets.yaml
|
||||
git commit -m "chore: add Vaultwarden admin token secret
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
After completing all tasks:
|
||||
1. Nginx module supports extra locations for WebSocket endpoints
|
||||
2. Vaultwarden will be accessible at `https://vault.ashisgreat.xyz`
|
||||
3. WebSocket sync enabled for real-time updates
|
||||
4. Admin panel accessible at `/admin` with the configured token
|
||||
5. SQLite database persisted in Podman volume `vaultwarden-data`
|
||||
Loading…
Add table
Add a link
Reference in a new issue