Local Development¶

Stage: Alpha Status: In Progress

This section is the contributor workflow for running IronRoot from a local Git checkout. It is split into focused pages so you can jump directly to the task you need.

Local Development Pages¶

Page	Use it for
Up And Running	Build binaries, initialize `.localdev`, create local PKI, start the server, enroll a client, request a certificate, and monitor with `irtop`.
Multi-Root CA Development	Work with the multi-root and multi-intermediate CA metadata model, RBAC roles, token policies, example YAML, and `irtop` hierarchy view.
RBAC Development	Seed local RBAC role and token-policy metadata, verify `/v1/status/ca-hierarchy`, and test the `irtop` access display.
Testing And Verification	Run unit tests, e2e tests, docs builds, lint/vet, telemetry checks, and the recommended patch verification loop.
Troubleshooting	Fix common local problems such as wrong database/config, invalid bootstrap token, port conflicts, missing PKI files, TLS trust errors, and MkDocs dependencies.

Recommended First Path¶

For a fresh checkout, follow this order:

If you are working on CA hierarchy or irtop visualization, also read Multi-Root CA Development. If you are working on roles, permissions, or token policies, read RBAC Development.

Local Workspace Convention¶

Most contributor commands use a generated .localdev directory:

.localdev/
  config/
  data/
  pki/
    root/
    intermediate/
  certs/
  logs/
  tmp/

Generated private keys, certificates, SQLite databases, logs, and temporary files must stay out of Git.

Important Local Assumptions¶

The default local API listens on localhost:8443.
The default local server uses HTTP, not HTTPS, because server.tls.cert_file and server.tls.key_file are empty.
Bootstrap tokens are stored in the SQLite database from the config passed to ironroot-admin create-token.
The server used for enrollment must be running with the same config/database that created the token.
Local demo CA material is disposable. Do not reuse it in production.