Local Development: Up And Running¶

Stage: Alpha Status: In Progress

This page gets a contributor checkout running with a local SQLite database, local Root CA, local Intermediate CA, server, client enrollment, certificate issuance, and irtop.

Prerequisites¶

Required:

Go
Git
just
SQLite

Optional:

Podman for container examples
Helm for chart work
Python and MkDocs dependencies for docs
golangci-lint and govulncheck for deeper checks

Verify tools:

go version
git --version
just --version
sqlite3 --version

Clone And Build¶

git clone https://github.com/parisnakitakejser/ironroot.git
cd ironroot
just build-local

Expected output:

bin/
  ironroot-server
  ironroot-admin
  ironroot-client
  ironroot-dev
  irtop

Install into ~/.local/bin:

just install-local
export PATH="$HOME/.local/bin:$PATH"

Verify:

ironroot-server --version
ironroot-admin --help
ironroot-client --help
ironroot-dev dev-init --help
irtop --help

Initialize `.localdev`¶

ironroot-dev dev-init

This creates:

.localdev/
  config/config.yaml
  config/rbac/local-rbac.yaml
  data/
  pki/root/
  pki/intermediate/
  certs/
  logs/
  tmp/

The generated config uses absolute paths under .localdev, SQLite at .localdev/data/ironroot.db, API address localhost:8443, file-based RBAC manifests under .localdev/config/rbac, telemetry disabled by default, and JSON logs to stdout.

Create Local PKI¶

Generate a local Root CA:

ironroot-admin ca create-root \
  --name "IronRoot Local Root CA" \
  --key-password ironroot-local-root \
  --out .localdev/pki/root

Generate a local Intermediate CA:

ironroot-admin ca create-intermediate \
  --root-cert .localdev/pki/root/root-ca.crt \
  --root-key .localdev/pki/root/root-ca.key \
  --root-password ironroot-local-root \
  --password ironroot-local-intermediate \
  --out .localdev/pki/intermediate

Inspect the generated material:

ironroot-admin ca inspect \
  --output table \
  .localdev/pki/root/root-ca.crt \
  .localdev/pki/intermediate/intermediate-ca.crt

Run bootstrap checks:

ironroot-admin bootstrap \
  --config .localdev/config/config.yaml \
  --non-interactive \
  --acknowledge-risk

Start The Server¶

ironroot-server --config .localdev/config/config.yaml

For quick iteration:

go run ./cmd/server --config .localdev/config/config.yaml

Or:

just run-server

The local server uses HTTP on localhost:8443.

Create A Bootstrap Token¶

In another terminal:

ironroot-admin create-token \
  --config .localdev/config/config.yaml \
  --host demo.local \
  --ttl 24h

Copy the returned token. The token is stored in the SQLite database from .localdev/config/config.yaml.

Enroll A Client¶

ironroot-client enroll \
  --server http://localhost:8443 \
  --hostname demo.local \
  --token <token>

--hostname must match the --host value used when the token was created. Copy the returned enrollment_id; certificate requests use that UUID, not the bootstrap token.

Request A Test Certificate¶

ironroot-client request-cert \
  --server http://localhost:8443 \
  --enrollment-id <enrollment_id> \
  --dns demo.local \
  --out .localdev/certs/demo.local

Inspect generated files:

find .localdev/certs/demo.local -maxdepth 1 -type f -print
cat .localdev/certs/demo.local/README.txt
cat .localdev/certs/demo.local/metadata.json

Verify the issued certificate chain:

openssl verify \
  -CAfile .localdev/pki/root/root-ca.crt \
  -untrusted .localdev/pki/intermediate/intermediate-ca.crt \
  .localdev/certs/demo.local/tls.crt

Monitor With irtop¶

irtop --server http://localhost:8443

One-shot text output:

irtop --server http://localhost:8443 --output text

Using the example config:

irtop --config examples/irtop.local.yaml

If you use HTTPS against the local HTTP server, irtop returns a clear HTTP/HTTPS mismatch hint. It does not silently downgrade.

Local Trust¶

Install the Root CA public certificate as the trust anchor:

.localdev/pki/root/root-ca.crt

Do not install private keys as trust material:

.localdev/pki/root/root-ca.key
.localdev/pki/intermediate/intermediate-ca.key

Debian/Ubuntu:

sudo cp .localdev/pki/root/root-ca.crt /usr/local/share/ca-certificates/ironroot-local.crt
sudo update-ca-certificates

Fedora/RHEL:

sudo cp .localdev/pki/root/root-ca.crt /etc/pki/ca-trust/source/anchors/ironroot-local.crt
sudo update-ca-trust