stack.basicstack.de/apps/stalwart/stalwart-bootstrap-completion-guide.md

# Stalwart 0.16 Bootstrap Wizard Completion Guide

## Current Status

- ✅ Pod running: `stalwart-0` in namespace `stalwart`
- ✅ JMAP API accessible (tested)
- ✅ OIDC credentials prepared in Kubernetes secret
- ⏳ Bootstrap wizard awaiting completion

## Bootstrap Access Credentials

**URL**: https://mail.basicstack.de/admin  
**Username**: `admin`  
**Password**: `YFMySjQYfMB3tYZa`

> **Note**: These credentials are valid only until the bootstrap wizard is completed, then they will be automatically disabled.

## OIDC Configuration Details

Retrieved from Kubernetes secret `stalwart-oidc` in namespace `stalwart`:

```
Client ID: 0f37a0e3-8d3b-4413-a394-36226f42a980
Client Secret: LPo8VejJXznisTQ87TGAs4Ad0Typ1MJw
Issuer URL: https://auth.basicstack.de
Redirect URI: https://mail.basicstack.de/admin/oauth/callback
Scopes: openid profile email
```

## Step-by-Step Bootstrap Wizard Completion

### Step 1: Access Bootstrap Interface

1. Open browser to: https://mail.basicstack.de/admin
2. Login with bootstrap credentials:
   - Username: `admin`
   - Password: `YFMySjQYfMB3tYZa`

### Step 2: Configure Data Store

The wizard should show the data store configuration. This is likely auto-configured:

- **Type**: RocksDB
- **Path**: `/opt/stalwart-mail/data`

Verify the settings and proceed.

### Step 3: Set Up OIDC Authentication

Configure OAuth/OIDC provider with these exact settings:

| Field | Value |
|-------|-------|
| Provider Name | Pocket ID |
| Issuer URL | `https://auth.basicstack.de` |
| Client ID | `0f37a0e3-8d3b-4413-a394-36226f42a980` |
| Client Secret | `LPo8VejJXznisTQ87TGAs4Ad0Typ1MJw` |
| Redirect URI | `https://mail.basicstack.de/admin/oauth/callback` |
| Scopes | `openid profile email` |

**Authorization Endpoint** (auto-discovered): `https://auth.basicstack.de/api/oidc/authorize`  
**Token Endpoint** (auto-discovered): `https://auth.basicstack.de/api/oidc/token`  
**UserInfo Endpoint** (auto-discovered): `https://auth.basicstack.de/api/oidc/userinfo`

### Step 4: Create/Link Administrator Account

Choose **Option A** (recommended): Link to Pocket ID user

- When prompted, link the admin account to a Pocket ID user
- The Pocket ID OIDC client is already configured with group restrictions
- Only users in the `Stalwart-admin` group can access

If the wizard requires creating an internal admin first:
- Create a temporary internal admin
- Link it to OIDC
- The bootstrap password login will be automatically disabled after setup

### Step 5: Disable Password Authentication (if prompted)

- **Web UI Authentication**: OIDC only
- **Mail Client Authentication**: Uses internal directory (separate from web UI auth)

This ensures the web admin interface only accepts OIDC login while mail clients continue to work normally.

### Step 6: Complete Setup

1. Review all configuration
2. Click "Complete Setup" or equivalent final button
3. The system will:
   - Save configuration to RocksDB
   - Exit bootstrap mode
   - Disable the bootstrap credentials
   - Enable OIDC authentication

### Step 7: Verify OIDC Login

1. Log out from the bootstrap session
2. Access https://mail.basicstack.de/admin again
3. Click "Login with Pocket ID" or the OAuth login button
4. Should redirect to https://auth.basicstack.de for authentication
5. After successful Pocket ID login, should return to Stalwart admin interface

## Post-Bootstrap Verification

Run these commands to verify the configuration:

```bash
# Check pod is still running
export KUBECONFIG=/paperclip/instances/default/workspaces/b4536334-39f2-4e05-b2f1-bb0e4670fba8/k3s.kubeconfig
/paperclip/instances/default/workspaces/b4536334-39f2-4e05-b2f1-bb0e4670fba8/bin/kubectl get pods -n stalwart

# Test JMAP API (should still work with OIDC credentials now)
curl -s -X POST https://mail.basicstack.de/jmap \
  -H "Content-Type: application/json" \
  -d '{"using":["urn:ietf:params:jmap:core"],"methodCalls":[["Core/echo",{"test":"post-bootstrap"},"0"]]}'

# Verify management API is now accessible
curl -s https://mail.basicstack.de/api/session
```

## Troubleshooting

### Issue: Cannot access bootstrap UI
- Verify pod is running: `kubectl get pods -n stalwart`
- Check pod logs: `kubectl logs stalwart-0 -n stalwart`
- Verify ingress: `kubectl get ingress -n stalwart`

### Issue: OIDC login not working after setup
- Check Stalwart logs for OAuth errors
- Verify redirect URI matches exactly
- Confirm user is in `Stalwart-admin` group in Pocket ID
- Test Pocket ID OIDC client directly

### Issue: Bootstrap credentials don't work
- Pod may have been restarted and new credentials generated
- Check parent issue DEV-155 for any updates
- May need to restart the pod or check the deployment

## Security Notes

- Bootstrap credentials automatically expire after setup completion
- OIDC client secret is stored in Kubernetes secret `stalwart-oidc`
- Access restricted to `Stalwart-admin` group members only
- All communication over HTTPS/TLS

## References

- Parent Issue: DEV-155
- OIDC Client configured in Pocket ID (client ID: 0f37a0e3-8d3b-4413-a394-36226f42a980)
- User Group: `Stalwart-admin` (group ID: 99ffc3ae-0112-4fa0-bec9-90da19bdaddd)
- Pocket ID: https://auth.basicstack.de
- Stalwart: https://mail.basicstack.de

## Acceptance Criteria Checklist

- [ ] Bootstrap setup wizard completed
- [ ] OIDC authentication configured with Pocket ID
- [ ] Can login to web UI via Pocket ID
- [ ] Password login disabled for web UI
- [ ] Bootstrap mode exited
- [ ] Configuration saved to RocksDB
- [ ] Management API responding (not "no available server")