# Vaultwarden Deployment Runbook

## Purpose

Plan and execute a safe Vaultwarden/Bitwarden-compatible vault deployment for the homelab.

This runbook is planning-first. Do not create the VM, install Vaultwarden, configure DNS/TLS, or migrate critical secrets until the approval gates below are satisfied.

## Approved Direction

- Deploy Vaultwarden in a dedicated Proxmox VM, not an LXC.
- Treat the vault VM as critical infrastructure.
- Expose the vault to LAN and Tailscale only by default.
- Do not configure public port forwarding or public reverse proxy exposure without a separate security review.
- Do not grant assistant direct vault access in the MVP.
- Establish a basic backup before relying on the vault for critical secrets.
- Perform a restore test soon after initial backup setup.

## Required User/Proxmox Details Before Implementation

Do not proceed past planning until these are approved:

- Proxmox node: likely `buntbox01`; confirm before implementation.
- VMID: use Proxmox default/next available VMID at creation time; record assigned numeric VMID after creation. User provided VM/name label `Vaultwarden`.
- VM hostname: `Vaultwarden` / `vw.dropcutstud.io` requested; confirm final OS hostname format before implementation.
- Vault FQDN/internal DNS name: `vw.dropcutstud.io` requested; user will handle LAN resolution separately with an Unbound override/exception.
- Static IP or DHCP reservation: DHCP approved.
- Network bridge/VLAN: default bridge approved; observed default bridge is likely `vmbr0`, confirm before implementation.
- Storage pool: default storage approved; likely `local-lvm` for VM disk, confirm before implementation.
- CPU/RAM/disk sizing: minimum required approved; recommended initial sizing is 1 vCPU, 1 GB RAM, 16 GB disk unless install method requires more.
- OS image/template: user approved assistant to choose; prefer Debian stable or Ubuntu LTS depending on easiest available Proxmox install path.
- Admin SSH access method: recommended `piagent` key-only SSH for deployment/maintenance using `scripts/bootstrap-assistant-ssh-user.sh`, with passwordless sudo during bootstrap; later reduce privileges if practical after Vaultwarden is stable.
- TLS strategy: defer DNS/provider automation for now. For the initial LAN-only deployment, use a self-signed/internal certificate or HTTP-only bootstrap temporarily if needed, but do not migrate real secrets until HTTPS is resolved.
- Tailscale reachability plan: deferred; handle separately after LAN deployment.
- Backup destination/encryption/retention: not currently available; tracked in `tickets/active/2026-06-06-vaultwarden-backup-plan.md`.
- Recovery/restore plan: not currently available; tracked in `tickets/active/2026-06-06-vaultwarden-recovery-restore-plan.md`.
- Snapshot/rollback plan: take Proxmox snapshots/checkpoints after OS install/hardening, after Vaultwarden install/configuration, before TLS/network changes, before first credential migration, and before updates; rollback by reverting to last known-good snapshot or destroying the VM before critical migration.
- Proxmox API token scope/revocation plan: use current broad bootstrap token only for creation if needed, then revoke/reduce it after VM deployment; create a future limited token scoped to the assigned Vaultwarden VM for power/status/snapshot operations and avoid broad datacenter privileges for routine maintenance.

## Suggested Baseline Sizing

These are starting points only and must be approved before use:

- vCPU: 1
- RAM: 1 GB
- Disk: 16 GB minimum; increase to 32 GB if attachments/sends will be heavily used
- OS: Debian stable or Ubuntu LTS; assistant may choose based on available Proxmox image/template path
- Storage: default Proxmox VM-capable storage, likely `local-lvm` if still appropriate

## Network and TLS Requirements

- Vault UI/API must use HTTPS.
- Default exposure is LAN plus Tailscale only.
- Public internet exposure is not approved by default.
- User requested `vw.dropcutstud.io` and will set up a LAN Unbound override/exception.
- Ignore public DNS/DNS-provider automation for the moment.
- Tailscale reachability is deferred and should be handled separately.
- TLS remains undecided and must be resolved before real credential entry or production use.
- Initial TLS/bootstrap options:
  - Internal/self-signed certificate for LAN testing, accepting client trust friction.
  - Temporary HTTP-only bootstrap on LAN for setup only, with no real secrets migrated until HTTPS is resolved.
  - Later DNS-01 Let's Encrypt, Tailscale cert, or internal CA once the user chooses.

## Admin Access Model

- Use dedicated administrative accounts.
- Use SSH key authentication for VM administration.
- Avoid shared root-password workflows.
- Keep assistant vault access out of MVP.
- If assistant SSH is needed for deployment, use the documented `piagent` grant/revoke process and log it.

## Service Deployment Approach

Final deployment method is not yet approved. Candidate approaches:

1. Docker Compose inside the dedicated VM.
2. Native package/binary/service management inside the VM.
3. Ansible or other reproducible automation later.

For the initial deployment, prefer the simplest approach that is easy to back up, restore, inspect, and update.

## Preflight Checklist

Before creating the VM:

- [x] User approves Proxmox default/next available VMID allocation, minimum sizing, no public exposure, and asks assistant to recommend admin SSH, TLS, snapshot rollback, and token scope plans.
- [x] User provided VM/name label, hostname/FQDN, DHCP, default bridge, default storage, and assistant-selected OS preference.
- [x] DNS provider/API path intentionally deferred; user will handle LAN resolution with Unbound.
- [ ] Confirm `piagent` bootstrap/maintenance SSH model.
- [ ] Confirm snapshot names/timing and broad-token revocation timing before creation.
- [ ] User approves LAN/Tailscale-only access boundary.
- [ ] User confirms no public port forwarding is planned.
- [ ] User approves final TLS strategy.
- [ ] User approves backup destination/encryption/retention.
- [ ] User confirms recovery material will be stored outside the vault.
- [ ] Snapshot/rollback plan is documented.
- [ ] Proxmox token scope/revocation plan is documented.
- [ ] `docs/server-change-log.md` entry plan is ready.

## Go / No-Go Gate

Proceed only if all are true:

- The VM will be dedicated to Vaultwarden or vault-adjacent support only.
- The vault will not be publicly exposed.
- LAN DNS/Unbound handling is accepted as user-owned.
- TLS/bootstrap approach is approved for setup; real credential migration remains blocked until HTTPS is resolved.
- Backup approach is approved.
- Recovery material has an out-of-vault storage plan.
- Rollback path is clear.

If any item is unclear, stop and ask the user.

## Current Proxmox Preflight Findings

Last checked: 2026-06-06, read-only API discovery.

- Node: `buntbox01`
- Assigned VMID: `102`
- Default bridge: `vmbr0`
- VM-capable storage:
  - `local-lvm` with `images,rootdir`
  - `m1`, `m2`, `m3` with `images`
- Default/recommended disk storage for MVP: `local-lvm`
- ISO storage: `local`
- Available ISO images:
  - `local:iso/debian-13.5.0-amd64-netinst.iso` — selected for Vaultwarden VM install
  - `local:iso/openmediavault_7.4.17-amd64.iso` — not suitable for Vaultwarden VM
- Available container templates only:
  - Debian 12/13 and Ubuntu 24.04 LXC templates; these do not satisfy the dedicated VM decision.

## Recommended Creation Plan

VMID `102` was created on 2026-06-06 and started from the Debian installer ISO.

Initial VM settings:

- Name: `Vaultwarden`
- FQDN: `vw.dropcutstud.io`
- OS: Debian 13.5 netinst ISO attached; OS installation pending
- vCPU: `1`
- RAM: `1024 MB`
- Disk: `16 GB` on `local-lvm`
- Network: DHCP on `vmbr0`
- Public exposure: none

Current installation blocker:

- VM shell exists and is running from the Debian installer ISO.
- OS installation likely requires Proxmox console interaction unless an unattended install method is added.
- After OS installation, configure SSH and bootstrap `piagent` access.

Admin bootstrap recommendation:

- During OS install, create or allow creation of an administrative account suitable for SSH bootstrap.
- After SSH is reachable, run `scripts/bootstrap-assistant-ssh-user.sh` to create `piagent` key-only access with temporary passwordless sudo for setup.
- After Vaultwarden is stable, reduce privileges if practical and document the final access model.

## High-Level Deployment Steps

Implementation details must be filled after approvals:

1. Confirm Proxmox node/storage/network state.
2. Create or upload approved OS image/template if needed.
3. Create VM with approved settings.
4. Install OS and apply security updates.
5. Create/administer SSH access according to approved model.
6. Install Vaultwarden using approved deployment method.
7. Configure TLS and LAN/Tailscale-only access.
8. Create initial admin/user setup according to user instructions.
9. Configure basic backup.
10. Verify service health and login.
11. Log deployment actions and rollback notes.

## Verification

- VM is running with approved configuration.
- Vaultwarden service is active.
- HTTPS endpoint works from approved LAN/Tailscale clients.
- Public internet exposure is absent unless separately approved.
- Backup job or manual backup procedure exists before critical migration.
- No secret values are written to git or logs.

## Rollback

Planning-only rollback:

- Revert this runbook or mark unapproved sections obsolete.

Deployment rollback, when implemented:

1. Stop Vaultwarden service.
2. Revert Proxmox snapshot or destroy VM if deployment is abandoned.
3. Remove DNS/reverse-proxy/firewall entries.
4. Remove or mark inventory entry retired.
5. Revoke temporary deployment access if any.
6. Log rollback in `docs/server-change-log.md`.

## 2026-06-06 Bootstrap Deployment Status

Current status: Vaultwarden bootstrap is deployed, reachable, and verified, but **not yet approved for critical secrets** because backup/restore and final hardening remain incomplete.

Approved user decisions captured during this session:

- Continue deployment.
- Use assistant-managed unattended/cloud-image path instead of manual console install.
- Use `piagent` temporary sudo for bootstrap administration.
- Use self-signed/internal TLS for initial LAN bootstrap.
- Defer backups for now; do not migrate critical secrets until backup is chosen and verified.
- Store recovery/break-glass material in an offline physical kit outside Vaultwarden.

Implemented state:

- Proxmox node: `buntbox01`
- VMID: `102`
- VM name/hostname: `Vaultwarden`
- DHCP IP observed: `192.168.0.238`
- Intended FQDN: `vw.dropcutstud.io`
- OS: Debian 13 generic cloud image
- Admin bootstrap user: `piagent`, key-only SSH, temporary passwordless sudo
- Runtime: Docker container `vaultwarden` from `vaultwarden/server:latest`
- Reverse proxy/TLS: Nginx with self-signed certificate for `vw.dropcutstud.io` and `192.168.0.238`
- Local service port: Vaultwarden bound to `127.0.0.1:8080`; Nginx listens on `80`/`443`
- Repo SSH alias: `vaultwarden-vm` in `.pi/ssh/hosts.json`
- Snapshots:
  - `pre-vaultwarden-install`
  - `post-vaultwarden-service-installed`

Current endpoint:

```text
https://vw.dropcutstud.io/   # after LAN DNS/Unbound override points to 192.168.0.238
https://192.168.0.238/       # works with certificate warning/self-signed mismatch considerations
```

Verification performed:

- SSH login as `piagent` succeeded.
- `docker`, `nginx`, `qemu-guest-agent`, and `vaultwarden` were active.
- QEMU guest agent ping succeeded from Proxmox after installation.
- HTTPS request with local DNS override returned HTTP `200`.
- Vaultwarden reported version `1.36.0` / Web-Vault `2026.4.1`.

Current locked-down state:

- User initial account creation was completed, then open signups were disabled.
- `SIGNUPS_ALLOWED=false` and `INVITATIONS_ALLOWED=false` were recorded in the 2026-06-06 change log after hostname correction.
- No admin token was configured or logged.
- No critical secrets should be entered until backup and recovery requirements are satisfied or the user explicitly accepts that risk.

Immediate next steps:

1. User adds/validates LAN DNS/Unbound override: `vw.dropcutstud.io -> 192.168.0.238`.
2. Decide and implement the Vaultwarden backup MVP before migrating critical secrets.
3. Reduce or remove temporary `piagent` sudo if practical after deployment hardening.
4. Pin/update strategy for the Vaultwarden Docker image should be selected before routine operations.
5. Design controlled assistant Vaultwarden access using a dedicated non-admin assistant identity and scoped collections/items.