portioner/vaultwarden/SETUP.md

# Service Setup Guide: Vaultwarden

Vaultwarden is a lightweight, community-driven server implementation of the Bitwarden API, written in Rust. It provides full compatibility with official Bitwarden clients (Web, iOS, Android, Desktop, Extensions).

## 1. Pre-Setup (Manual)
### Create Service User
- [ ] **Manual**: Create a local user named `svc-vaultwarden` in Synology DSM (Control Panel > User & Group).
- [ ] **Manual**: Give this user read/write access to the `docker` shared folder.

### Get User IDs
- [ ] **Manual**: SSH into your NAS and run `sudo synouser --get svc-vaultwarden`.
- [ ] **Confirmed IDs**: Locate the `User ID` (PUID) and `Group ID` (PGID).
- [ ] **Action**: Open `create_vaultwarden_folders.sh` and update the `USER_ID="[PUID]:[PGID]"` line.
- [ ] **Action**: Use these values in your Portainer stack environment variables (`stack.env`).

## 2. Infrastructure Setup
### Run Setup Script
- [ ] **Action**: Run the setup script in Dry-Run mode to verify changes:
  ```bash
  sudo bash create_vaultwarden_folders.sh
  ```
- [ ] **Action**: Apply the folder creation and ownership settings:
  ```bash
  sudo bash create_vaultwarden_folders.sh --run
  ```
- **What it does**: 
  - Creates `/volume1/docker/vaultwarden/data` for the SQLite database and attachments.
  - Sets ownership securely to the `svc-vaultwarden` user, ensuring the container writes files non-root.

## 3. Portainer Deployment
### Environment Variables
- [ ] **Action**: In the Portainer Stack configuration, upload or define the variables from `stack.env`.
  - Important: Ensure `DOMAIN` is set correctly for WebAuthn/FIDO2 to function.
  - Temporary: Keep `SIGNUPS_ALLOWED=true` initially.
- [ ] **Action (Admin Token)**: The Vaultwarden Admin Panel requires a secure hash, not plain text. To generate it, SSH into your NAS and run:
  ```bash
  docker run --rm -it vaultwarden/server vaultwarden hash
  ```
  Enter your desired admin password, copy the generated `$$argon2id$$...` string, and paste it as the `ADMIN_TOKEN` value.

### Deploy Stack
- [ ] **Action**: Create a new stack named `vaultwarden-stack`.
- [ ] **Action**: Paste the content of `docker-compose.portainer.yml` and deploy.
- [ ] **Verification**: Access the Vaultwarden Web UI at `http://[NAS_IP]:8020`.

## 4. Post-Setup Security (Crucial)
1.  **Create your account**: Navigate to the Web UI, click "Create Account", and register your master email and password.
2.  **Disable Signups**: Once your account is created, go back to Portainer, update the stack environment variable `SIGNUPS_ALLOWED=false`, and **Redeploy** the stack. This prevents unauthorized users from registering on your personal instance.
3.  **Reverse Proxy / HTTPS**: Vaultwarden **requires** active HTTPS (SSL) for many features like Bitwarden browser extensions or the admin page to load correctly. Point your Traefik/Cloudflared tunnel to this container.