mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Write OpenBao documentation and production hardening guide #354

New Issue
Closed
opened 2026-02-07 17:11:41 +00:00 by jason.woltje · 0 comments
jason.woltje commented 2026-02-07 17:11:41 +00:00
Owner
Copy Link

Phase 2d - Documentation

Problem

OpenBao integration needs comprehensive documentation for both development use and production hardening. Operators need to understand the turnkey defaults, how to upgrade security for production, and how the Transit encryption architecture works.

Requirements

  1. Create docs/OPENBAO.md covering setup, architecture, and operations
  2. Document the turnkey auto-init/auto-unseal behavior
  3. Document production hardening steps (Shamir upgrade, TLS, HA, audit logging)
  4. Document the Transit encryption architecture and key hierarchy
  5. Document AppRole authentication flow
  6. Document disaster recovery procedures

Topics to Cover

  • Overview: why OpenBao, what Transit engine does
  • Architecture diagram: API -> VaultService -> OpenBao Transit -> PostgreSQL
  • Default setup: 1-of-1 key share, file storage, auto-unseal
  • Environment variables: OPENBAO_ADDR, OPENBAO_ROLE_ID, OPENBAO_SECRET_ID
  • Named encryption keys and their purposes
  • Fallback behavior when OpenBao is unavailable
  • Production hardening checklist
  • Key rotation procedures (Transit handles versioning transparently)
  • Backup and restore procedures
  • Troubleshooting common issues

Files

  • docs/OPENBAO.md (new)

Acceptance Criteria

  • Documentation covers all topics listed above
  • Production hardening steps are actionable
  • Architecture diagram included
  • Linked from main docs and CLAUDE.md

Dependencies

  • Depends on: OpenBao Docker setup (need working implementation to document)

Refs #346

## Phase 2d - Documentation ### Problem OpenBao integration needs comprehensive documentation for both development use and production hardening. Operators need to understand the turnkey defaults, how to upgrade security for production, and how the Transit encryption architecture works. ### Requirements 1. Create docs/OPENBAO.md covering setup, architecture, and operations 2. Document the turnkey auto-init/auto-unseal behavior 3. Document production hardening steps (Shamir upgrade, TLS, HA, audit logging) 4. Document the Transit encryption architecture and key hierarchy 5. Document AppRole authentication flow 6. Document disaster recovery procedures ### Topics to Cover - Overview: why OpenBao, what Transit engine does - Architecture diagram: API -> VaultService -> OpenBao Transit -> PostgreSQL - Default setup: 1-of-1 key share, file storage, auto-unseal - Environment variables: OPENBAO_ADDR, OPENBAO_ROLE_ID, OPENBAO_SECRET_ID - Named encryption keys and their purposes - Fallback behavior when OpenBao is unavailable - Production hardening checklist - Key rotation procedures (Transit handles versioning transparently) - Backup and restore procedures - Troubleshooting common issues ### Files - docs/OPENBAO.md (new) ### Acceptance Criteria - [ ] Documentation covers all topics listed above - [ ] Production hardening steps are actionable - [ ] Architecture diagram included - [ ] Linked from main docs and CLAUDE.md ### Dependencies - Depends on: OpenBao Docker setup (need working implementation to document) Refs #346
jason.woltje added this to the M9-CredentialSecurity (0.0.9) milestone 2026-02-07 17:11:41 +00:00
jason.woltje added the securityp2 labels 2026-02-07 17:11:41 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
ai
AI/LLM integration
 api
Backend/API work
 api
auth
Authentication
 database
database
Database/schema work
 devops
Docker/deployment
 docs
Documentation
 frontend
graph
knowledge-module
migration
Data migration
 orchestrator
Orchestrator service (apps/orchestrator/)
 p0
Critical priority
 p1
High priority
 p2
Medium priority
 p3
Low priority
 performance
Performance work
 phase-1
phase-2
phase-3
phase-4
phase-5
plugin
MoltBot plugin work
 search
security
Security-related
 setup
Initial setup
 testing
Testing/QA
 web
Frontend work
No Label p2 security
Milestone
No items
No Milestone M9-CredentialSecurity (0.0.9)
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaic/stack#354
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?