Infralink Ops

BLUF

This repo packages the public controller runtime for managed hosts. Deployment intent, private templates, and secret aliases remain in the environment registry; live-service acceptance remains environment-owned operational state.

Use it when you need bounded host primitives for registry checkout, template rendering, config projection, Docker image retention, Compose consumer activation, firewall verification, secret rendering, or host doctor evidence.

Do not use this repo to select fleet desired state. Registry revisions, service definitions, image pins, hostnames, and secret bindings come from the environment registry.

Reader Paths

How It Fits

flowchart LR
    registry["configured registry revision"] --> checkout["/var/lib/infralink/registry"]
    checkout --> render["template render and static config projection"]
    render --> consumers["Compose consumer validate/activate"]
    consumers --> evidence["doctor, metrics, and logs"]
    evidence --> operator["environment-owned acceptance"]

This repo implements the bounded primitives in the middle of the flow. It does not own the registry data model or the environment-specific acceptance result.

Main CLIs

Each command is intentionally narrow. Commands receive explicit inputs and return bounded machine-readable envelopes where possible.

Authority Boundary

For RelayOS IRC, source/config/image repos feed the registry first:

flowchart LR
    deploy["relayos-deploy docs and deploy contract"]
    config["relayos-irc-config"]
    modules["custom-modules"]
    images["relayos-irc-containers"]
    registry["infra-registry"]
    ops["infralink-ops controller"]
    host["managed host"]

    config --> registry
    modules --> images
    images --> deploy
    deploy --> registry
    registry --> ops
    ops --> host

GHCR and BWS

The controller image publishes to cyberstorm-dev packages as ghcr.io/cyberstorm-dev/infralink-ops-controller.

BWS access is runtime-only. This repo contains the resolver and tests for the resolver contract; the token and secret object names belong to the environment registry and host runtime.

Verify Changes

Run the same checks Woodpecker runs:

python -m pip install --disable-pip-version-check \
  'infralink @ https://github.com/cyberstorm-dev/infralink/releases/download/v0.6.14/infralink-0.6.14-py3-none-any.whl#sha256=e41e16e082df50d7506785feb40dc3ea48087d46c391e31f2bd77e3ef81ce0e3'
python -m pip install --disable-pip-version-check -e '.[dev]'
python -m ruff check src tests
python -m ruff format --check src tests
python -m pytest -q
python -m build

Infralink Ops declares compatibility with Infralink >=0.6,<0.7. Until Infralink is published to PyPI, bootstrap a released, checksum-pinned wheel before installing Ops so a clean environment does not attempt an unavailable index resolution.

The controller image publish step runs only on main pushes. Pull requests use Docker buildx dry-run validation.

Triage A Stale Host

Check in this order:

1. Confirm the environment selected the intended registry revision.
2. Confirm /var/lib/infralink/registry has the expected checkout.
3. Run infralink-host doctor for read-only host evidence.
4. Inspect /var/lib/infralink/reconcile-result.yml as the last reconcile result, not as desired state.
5. Check whether infralink-host-reconcile.timer ran after the registry change.
6. Check rendered files under /opt/services/config.
7. Check the affected Compose service or application-specific behavior.

Do not repair desired-state drift by editing /opt/services directly. Fix the registry or source repo that owns the value, then let the controller reconcile.

Development Contract

• Keep commands agent-friendly: explicit inputs, bounded output, stable exit behavior, and machine-readable evidence.
• Keep provider-specific policy out of generic primitives unless the command name says it is provider-specific.
• Add tests for every command contract, runtime boundary, and failure mode.
• Keep README-level docs focused on operator entrypoints; put command-specific details in focused guides or tests.