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:

# 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")