echo6-docs/runbooks/vaultwarden-deployment.md

# Vaultwarden Deployment

**Deployed:** 2026-02-05
**Location:** Contabo VPS (5.189.158.149 / 100.64.0.6)
**URL:** https://vault.echo6.co

---

## Service Details

| Setting | Value |
|---------|-------|
| Container | `vaultwarden` |
| Image | `vaultwarden/server:latest` |
| Port | `127.0.0.1:8086` (web), `127.0.0.1:3012` (websocket) |
| Data | `/opt/vaultwarden/data` |
| Config | `/opt/vaultwarden/.env` |
| SSO | Authentik (enabled) |
| Signups | Disabled (invite-only) |

---

## Access

| Method | URL |
|--------|-----|
| Web Vault | https://vault.echo6.co |
| Admin Panel | https://vault.echo6.co/admin |
| SSO Login | "Enterprise Single Sign-On" button |

---

## Configuration Files

### Docker Compose (`/opt/vaultwarden/docker-compose.yml`)

```yaml
services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:8086:80"
      - "127.0.0.1:3012:3012"
    volumes:
      - ./data:/data
    environment:
      - TZ=America/Boise
```

### Environment (`.env`)

```bash
# Admin
ADMIN_TOKEN=<see credentials file>
DOMAIN=https://vault.echo6.co

# Security
SIGNUPS_ALLOWED=false
INVITATIONS_ALLOWED=true
SHOW_PASSWORD_HINT=false

# WebSocket
WEBSOCKET_ENABLED=true

# SSO (Authentik)
SSO_ENABLED=true
SSO_ONLY=false
SSO_CLIENT_ID=vaultwarden
SSO_CLIENT_SECRET=<see credentials file>
SSO_AUTHORITY=https://auth.echo6.co/application/o/vaultwarden/
SSO_PKCE=true
SSO_SCOPES="openid email profile offline_access"

# Timezone
TZ=America/Boise
LOG_LEVEL=info
```

### Caddy Site Block

```caddyfile
vault.echo6.co {
    reverse_proxy /notifications/hub 127.0.0.1:3012
    reverse_proxy 127.0.0.1:8086
}
```

### dnsmasq Split DNS

```conf
address=/vault.echo6.co/100.64.0.6
```

---

## Authentik SSO Configuration

### Provider Settings (pk=3)

| Setting | Value |
|---------|-------|
| Name | Vaultwarden |
| Client ID | `vaultwarden` |
| Client Type | Confidential |
| Redirect URI | `https://vault.echo6.co/identity/connect/oidc-signin` |
| Signing Key | authentik Internal JWT Certificate (RS256) |
| Access Token Validity | 1 hour |
| Refresh Token Validity | 30 days |

### Scopes

- `openid` - Required for OIDC
- `email` - User email
- `profile` - User profile
- `offline_access` - Refresh tokens

### OIDC Endpoints

| Endpoint | URL |
|----------|-----|
| Discovery | https://auth.echo6.co/application/o/vaultwarden/.well-known/openid-configuration |
| JWKS | https://auth.echo6.co/application/o/vaultwarden/jwks/ |
| Authorize | https://auth.echo6.co/application/o/authorize/ |
| Token | https://auth.echo6.co/application/o/token/ |

---

## Troubleshooting

### SSO Login Loop

**Symptom:** After SSO auth, redirects back to login screen.

**Causes:**
1. Access token too short (< 5 min)
2. Missing `offline_access` scope (no refresh token)
3. Missing signing key (empty JWKS)

**Fix:**
```bash
# Check Authentik provider settings via ak shell
docker exec authentik-server ak shell -c "
from authentik.providers.oauth2.models import OAuth2Provider
p = OAuth2Provider.objects.get(name='Vaultwarden')
print(f'Access Token: {p.access_token_validity}')
print(f'Signing Key: {p.signing_key}')
print(f'Scopes: {list(p.property_mappings.values_list(\"scope_name\", flat=True))}')"
```

### SSO Discovery Error

**Symptom:** "Failed to discover OpenID provider: Failed to parse server response"

**Causes:**
1. Empty JWKS endpoint (no signing key)
2. Missing property mappings

**Fix:** Add signing key and scopes to Authentik provider.

### View Logs

```bash
# Vaultwarden
docker logs vaultwarden --tail 100 2>&1 | grep -i -E "sso|error"

# Authentik
docker logs authentik-server --tail 100 2>&1 | grep -i vaultwarden
```

---

## Maintenance

### Restart Service

```bash
ssh root@5.189.158.149
cd /opt/vaultwarden
docker compose restart
```

### Update Image

```bash
ssh root@5.189.158.149
cd /opt/vaultwarden
docker compose pull
docker compose up -d
```

### Backup Data

```bash
# Stop container first
docker compose stop
tar -czf vaultwarden-backup-$(date +%Y%m%d).tar.gz data/
docker compose start
```

---

## Credentials Reference

All credentials stored in `/home/zvx/projects/.ref/credentials`:

```
VAULTWARDEN_URL
VAULTWARDEN_ADMIN_TOKEN
VAULTWARDEN_ADMIN_URL
VAULTWARDEN_OIDC_PROVIDER_ID
VAULTWARDEN_OIDC_CLIENT_ID
VAULTWARDEN_OIDC_CLIENT_SECRET
VAULTWARDEN_OIDC_ISSUER
```

---

*Last updated: 2026-02-05*