bootroot

bootroot is a product-embedded PKI bootstrap and trust foundation. It uses OpenBao to manage secrets and provides a CLI-first workflow to bring up a private CA and issue/renew mTLS certificates.

bootroot is the umbrella name for:

• bootroot CLI (bootroot)
• bootroot-agent (bootroot-agent)
• bootroot-remote (bootroot-remote)
• HTTP-01 responder (bootroot-http01-responder)
• Prometheus (monitoring)
• Grafana (monitoring dashboards)

Open source dependencies:

• step-ca: ACME-compatible private CA
• OpenBao: secret manager (Vault-compatible KV v2)
• PostgreSQL: step-ca database
• Prometheus: metrics collection
• Grafana: metrics visualization

Architecture Summary

• Single-machine default: bootroot infra install performs first-time setup (generates .env, creates secrets/ and certs/ directories, and brings up Docker Compose with --build). bootroot init then bootstraps OpenBao, step-ca, and rotates the DB password. bootroot infra up restarts an already-configured environment.
• Prebuilt / air-gapped: for an install without a source tree or network, point infra install at docker-compose.deploy.yml (no build: contexts, interpolatable image: tags), load the release images from local tarballs with --image-archive-dir, and pass --no-build to use them as-is (--no-build implies --pull never, so the install never reaches a registry). See the CLI reference (한국어).
• Monitoring: Prometheus scrapes step-ca/OpenBao metrics and Grafana visualizes them for local ops.
• Service onboarding: bootroot service add registers service metadata, creates an AppRole, automatically registers the HTTP-01 DNS alias on the responder, optionally configures a post-renew hook (--reload-style or --post-renew-command), writes the agent config (including the [openbao] fast-poll section) plus eab.json, and prints the host-daemon run command for bootroot-agent — no manual config editing required.
• Certificate flow: bootroot-agent runs as a host daemon that issues/renews certs and keeps its own secrets and config current via its fast-poll loop against OpenBao (trust bundle, AppRole secret_id, responder HMAC, EAB). OpenBao Agent serves only the infrastructure components (step-ca and the HTTP-01 responder).

For multi-machine deployments using --delivery-mode remote-bootstrap, see the Remote Bootstrap Operator Guide (한국어). For other manual deployment options, follow the manual guides in docs/.

Developer Layout

The bootroot-http01-responder binary now lives under src/bin/bootroot-http01-responder/ with focused modules for:

• configuration loading and reload
• in-memory token state
• HTTP request handlers
• HMAC/timestamp verification
• expired-token cleanup
• server startup and signal handling

Quick Start (CLI)

See docs/en/cli.md (EN) or docs/ko/cli.md (KO) for the full flow.

The full setup is documented in docs/en/installation.md and docs/ko/installation.md.

Typical first-time sequence:

bootroot infra install          # first-time setup
bootroot init                   # step-ca bootstrap (automatic)
bootroot service add
bootroot verify
bootroot rotate ...
bootroot monitoring up|status|down

After the initial install, use bootroot infra up to restart the already-configured environment. Use bootroot clean to tear down everything for a fresh start.

If bootroot init failed after OpenBao was initialised (the "partial-init" trap), or if a work directory was copied to a new host via rsync and the destination's stale state.json conflicts with a fresh OpenBao volume, use bootroot reinit to atomically wipe the OpenBao-owned state and re-run init while preserving step-ca CA material and any recorded non-loopback bind intent.

When copying a work directory between machines, exclude state.json, secrets/openbao/, and secrets/services/ from the rsync (these are machine-local) to avoid the partial-init trap on the destination host.

Documentation

• Design philosophy: DESIGN.md
• Manual entry point: docs/en/index.md (English)
• 매뉴얼 시작점: docs/ko/index.md (한국어)
• CLI guide (EN): docs/en/cli.md
• CLI guide (KO): docs/ko/cli.md

For detailed architecture, installation, configuration, and operations guides, refer to the manuals above.

Build locally:

brew install python
python3 -m venv .venv
# zsh/bash:
source .venv/bin/activate
# fish:
source .venv/bin/activate.fish
pip install mkdocs-material mkdocs-static-i18n
mkdocs serve -a 127.0.0.1:8000 --livereload --dirtyreload

Command notes:

• brew install python: installs Python (one-time per machine).
• python3 -m venv .venv: creates a local virtualenv for this repo.
• source .venv/bin/activate: activates the virtualenv for the current shell.
• pip install ...: installs MkDocs tooling into the virtualenv.
• Run the pip install ... step once after creating the virtualenv (per clone).
• mkdocs serve -a 127.0.0.1:8000 --livereload --dirtyreload: runs a local docs server.
• mkdocs build --strict: builds static files into site/.
• ./scripts/check-docs.sh: what CI runs — verifies the vendored theme, builds with --strict, and asserts the built pages link the theme stylesheets and that every referenced theme asset reached site/.
• ./docs/theme/build-docs-pdf.sh en|ko: builds PDF manuals into site/pdf/. Needs pip install mkdocs-with-pdf.

The shared docs theme is vendored under docs/theme/ and committed, so a fresh clone builds the manual with no network access and no gh. mkdocs.yml inherits docs/theme/mkdocs-base.yml for the theme, markdown extensions, and stylesheets; keep only site-specific keys in mkdocs.yml.

To move to a new theme release, edit version in docs/theme.toml, run ./scripts/fetch-theme.sh (this needs gh), and commit the resulting docs/theme/. Never edit files under docs/theme/ by hand — the installer records a digest in docs/theme/.meta and CI fails on any drift. Changes belong in aicers/docs-theme.

Docs Authoring Rules (list hierarchy)

To avoid rendered list hierarchy regressions in MkDocs Material:

• Prefer heading/label + single-level list over deep nested lists.
• If nesting is required, use 4-space indentation consistently.
• Keep a blank line before and after nested lists.
• Avoid mixing long free-form paragraphs between list markers where possible.
• For complex comparisons, prefer short table or separate subsection blocks.

Docs PR quick checklist:

• Run local preview for changed docs pages: mkdocs serve -a 127.0.0.1:8000 --livereload --dirtyreload
• Run markdown lint: markdownlint-cli2 "**/*.md" "#node_modules" "#target"
• Run the docs build check: ./scripts/check-docs.sh
• If both KR/EN pages were changed, verify wording/structure parity.

Preflight (required before push)

Run all preflight checks before pushing:

./scripts/preflight/run-all.sh

Or run individual scripts. Scripts under preflight/ci/ mirror CI workflow jobs; scripts under preflight/extra/ are local-only checks not in CI.

CI-equivalent (preflight/ci/)

Script	CI job
./scripts/preflight/ci/check.sh	ci.yml Quality Check
./scripts/preflight/ci/test-core.sh	ci.yml Unit & CLI Smoke
./scripts/preflight/ci/e2e-matrix.sh	ci.yml Docker E2E Matrix
./scripts/preflight/ci/e2e-extended.sh	e2e-extended.yml Run Extended

Local-only (preflight/extra/)

Script	Description
./scripts/preflight/extra/agent-scenarios.sh	Agent scenario tests
./scripts/preflight/extra/cli-scenarios.sh	CLI scenario tests

Notes:

• If your machine cannot run non-interactive sudo (sudo -n) for hosts mode, use ./scripts/preflight/ci/e2e-matrix.sh --skip-hosts.
• Artifacts are written under tmp/e2e/ for triage.

If Python formatting/linting fails, auto-fix first:

ruff format .
ruff check --fix .

Install scope:

• If you use a per-repo virtualenv (.venv), you need to create it and install dependencies each time you clone the repo.
• If you install MkDocs globally, it is a one-time machine install, but we recommend the per-repo virtualenv to avoid version conflicts.

License

Copyright 2026 ClumL Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License. You may obtain a copy of the License in the LICENSE file.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE file for the specific language governing permissions and limitations under the License.