Runbook: Laboratory Bootstrap

Status: living

This runbook describes the current intended integration boundary between:

• Dubnium
• ryjen/dotfiles
• hackelia-micrantha/laboratory

Dubnium owns machine orchestration and runtime policy.

Laboratory is the intended source of truth for:

• k3s bootstrap
• Flux bootstrap
• GitOps reconciliation
• local cluster lifecycle operations

Current State

The current Dubnium repository still contains a thin local k3s integration for v1 bring-up.

The long-term intended direction is:

• Dubnium owns host orchestration
• Laboratory owns cluster orchestration

This runbook defines the current bootstrap contract without pretending the full migration is already complete.

Expected Repository Shape

Typical local source layout:

~/local/src/
├── dubnium/
│   ├── external/dotfiles/
│   └── external/laboratory/

The external/laboratory checkout may be:

• a Git submodule
• a manually managed checkout
• another intentionally pinned local source path

The preferred integration ref today is:

feature/fresh

Bootstrap Flow

After the machine is operational:

1. validate Dubnium host state
2. validate user environment
3. bootstrap Laboratory
4. validate cluster state
5. fetch kubeconfig
6. validate Flux reconciliation

Prerequisites

Laboratory expects tooling such as:

• tofu or terraform
• ansible
• kubectl
• flux
• jq

See the Laboratory repository for current authoritative prerequisites.

Bootstrap Command

Dubnium exposes a thin wrapper entrypoint:

scripts/bootstrap-lab

The wrapper intentionally:

• validates the checkout exists
• validates the repository shape looks correct
• warns when the checkout ref differs from the preferred ref
• delegates execution into Laboratory

The wrapper intentionally does not duplicate Laboratory internals.

Environment Overrides

Optional overrides:

export DUBNIUM_LAB_PATH=~/local/src/laboratory
export DUBNIUM_LAB_REF=feature/fresh

Override the delegated bootstrap command:

export DUBNIUM_LAB_BOOTSTRAP_CMD='make deploy ENV=local'

Default Delegated Flow

Current default delegated flow:

make deploy ENV=local && \
make local-kubeconfig ENV=local && \
make validate ENV=local

This is intentionally conservative while the integration boundary evolves.

Failure Boundaries

If Laboratory bootstrap fails:

• Dubnium machine orchestration should still function
• mode transitions should still function
• user environment should still function
• only cluster capabilities should be degraded

Machine boot must not require successful Laboratory reconciliation.

Recovery

To retry the bootstrap:

scripts/bootstrap-lab

To validate current cluster state directly through Laboratory:

cd external/laboratory
make validate ENV=local