Skip to content

Developer Notes — Getting Started

What Is This Repo?

OVES's centralized documentation for secret management and trust infrastructure. It houses Architecture Decision Records (ADRs), implementation roadmaps, operational playbooks, and reference material — everything a team member needs to understand how OVES manages machine secrets and (eventually) trust services.

This is a docs-only repo. No application code. No deployments to production.

Repo: https://github.com/ovesorg/secret-manager (private)

Repo Location
Local d:\github\secret-manager
Remote github.com/ovesorg/secret-manager (private)
Doc-site mkdocs serve -a 127.0.0.1:8003
Branch master

Tech Stack

  • MkDocs with Material theme
  • Template: mkdocs-oves-template (company standard)
  • Python 3.12+ with requirements.txt dependencies

Quick Start

cd d:\github\secret-manager

# Install dependencies (first time only)
pip install -r requirements.txt

# Local preview
mkdocs serve -a 127.0.0.1:8003

Open http://127.0.0.1:8003 in your browser.

Directory Structure

secret-manager/
├── docs/
│   ├── index.md              # Landing page
│   ├── adr/                  # Architecture Decision Records
│   │   ├── index.md
│   │   └── 001-vault-oss-strategic-platform.md
│   ├── roadmap.md            # Phase 0 → Phase 3 implementation timeline
│   └── reference/            # Terminology, external links
├── mkdocs.yml                # Site config
├── requirements.txt
├── hooks/                    # Build hooks (auto-run by mkdocs)
└── .session.md               # Session journal (auto-maintained)

Current State (May 2026)

Item Status
ADR-001: Vault OSS as Strategic Platform Written — Proposed Baseline
Roadmap (Phase 0–3) Written
ADR-002: Vault Deployment Architecture Not started
ADR-003: Azure AD → Vault Auth Not started
ADR-004: Secret Injection Pattern Not started
Developer Onboarding Playbook Not started
Git Leak Detection Hook Not started
Rotation Policy Not started

Key decision (ADR-001): Vault OSS over Infisical/Doppler. Vault-Lite first (KV + auth + audit), expand to PKI/trust later.

How to Contribute

Writing a New ADR

  1. Create docs/adr/<NNN>-<short-title>.md
  2. Use ADR-001 as a template (copy the frontmatter block)
  3. Add it to the nav section in mkdocs.yml
  4. Update docs/adr/index.md if an index listing exists
  5. Build locally (mkdocs serve) and verify rendering
  6. Commit and push

Commit Convention

  • Use descriptive messages: adr: add ADR-002 vault deployment architecture
  • For session wrap-ups: wrap: YYYY-MM-DD — <summary>

Naming Rules

  • Repo name = remote name = folder name (all secret-manager)
  • ADR filenames: NNN-kebab-case.md
  • Keep titles short and scannable

Key Concepts (from ADR-001)

Phase 0 (Now)     → Stabilize human credentials (Bitwarden, passkeys, audit)
Phase 1 (2026 Q3) → Vault-Lite: KV engine + Azure AD/GitHub auth + audit
Phase 2 (2027)    → PKI: device certificates, MQTT mTLS, internal CA
Phase 3 (2028+)   → Asset Trust: battery identity, blockchain anchoring

Four trust layers: Identity (Azure AD) → Secrets (Vault) → Trust (PKI) → Proof (Blockchain)

Next Priorities

  1. ADR-002 — Vault deployment architecture (HA cluster? storage backend? auto-unseal?)
  2. ADR-003 — Azure AD → Vault auth integration design
  3. Onboarding playbook — Step-by-step guide for new developers to get Vault access
  4. Git leak detection — Pre-commit hooks using gitleaks or detect-secrets