Skip to main content

OSS Inventory

Helpifyr OSS Inventory Version Truth

This document defines the repo-owned OSS inventory and version-truth verification posture for Fabric-owned platform OSS families.

The canonical machine-readable sources remain:

  • contracts/platform/helpifyr_stack_module_identity_v1.json
  • contracts/platform/platform_version_truth.json
  • contracts/platform/platform_projection_catalog.json
  • contracts/platform/stack_tool_oss_inventory_directory.json
  • contracts/platform/integrated_system_inventory_crosswalk_v1.json
  • contracts/platform/platform_oss_upgrade_adoption_roles_v1.json
  • contracts/platform/platform_oss_upgrade_governance_v1.json
  • contracts/platform/platform_oss_upgrade_compatibility_matrix_v1.json
  • contracts/platform/platform_oss_upgrade_evidence_contract_v1.json
  • GET /api/v1/platform/version-truth
  • GET /api/v1/platform/projection-catalog
  • GET /api/v1/platform/tool-oss-inventory-directory

The companion operator-facing reference for this verify path lives in:

  • docs/OSS_INVENTORY_VERSION_TRUTH.md

The companion integrated-system reference for management-facing and architecture-facing software lists lives in:

  • docs/contracts/HELPIFYR_INTEGRATED_SYSTEM_INVENTORY_CROSSWALK.md

Scope​

This inventory and its upgrade companions are fail-closed for the following platform families:

  • grafana-oss
  • prometheus-oss
  • wikijs-oss
  • wikijs-proxy-nginx
  • dapr-runtime
  • shared-n8n
  • shared-nats
  • postgres-oss
  • otel-collector

Any missing family, version drift, :latest image tag, or doc/contract mismatch is a verification failure.

Integrated System Companion​

The narrow Fabric-owned platform inventory above is intentionally not the same thing as the broader integrated software landscape used across the Helpifyr stack.

Management-facing, partner-facing, and architecture-facing software lists must consume the complementary integrated-system crosswalk instead of widening the platform-family list above.

The current crosswalk explicitly covers the following integrated system groups:

  • enterprise and business systems: Alfresco Community Edition, ERPNext / Frappe, Zammad, Keycloak, Plane
  • workspace and collaboration systems: Nextcloud Hub, Collabora Online, Stalwart Mail Server
  • voice and telephony systems: Asterisk
  • infrastructure and shared platform services: OpenTofu, shared n8n, shared NATS, shared PostgreSQL, Dapr Runtime, Wiki.js
  • observability and delivery surfaces: Grafana OSS, Prometheus, Gitea
  • supporting runtime dependencies: Elasticsearch, ActiveMQ

Current posture notes:

  • OpenTofu is projected from jhf-deployment owner truth as the active IaC-core runtime/tooling posture.
  • Elasticsearch remains the currently observed active Zammad support dependency on Host172.
  • OpenSearch is not claimed as an active runtime here; it remains a migration target only and is tracked separately in JaddaHelpifyr/jhf-spindle#1212.

The canonical machine-readable source for those broader software lists is:

  • contracts/platform/integrated_system_inventory_crosswalk_v1.json

Verify Path (Fail-Closed)​

  1. python scripts/verify_platform_version_truth.py --check
  2. python scripts/verify_platform_oss_upgrade_contracts.py --check
  3. python scripts/verify_platform_oss_upgrade_adoption_contract.py --check
  4. python scripts/verify_stack_module_identity_contract.py --check
  5. python scripts/verify_oss_inventory_version_truth.py --check
  6. python scripts/verify_stack_tool_oss_inventory_directory.py --strict --source gitea-pinned --token-env FABRIC_READBACK_TOKEN --output contracts/platform/stack_tool_oss_inventory_directory.json
  7. python scripts/verify_integrated_system_inventory_crosswalk.py --workspace-root "$WORKSPACE_ROOT" --output contracts/platform/integrated_system_inventory_crosswalk_v1.json
  8. bash scripts/testing/run_beam_stack_oss_inventory_wave.sh

If any check fails, the OSS inventory truth is considered not-ready and must not be treated as green.

The checked-in stack-tool directory is built from commit-pinned owner truth in Gitea. Local workspace scanning is diagnostic-only and cannot supply the canonical persisted directory.

Upgrade Readiness Rule​

  • Upgrade planning must consume Fabric-owned version truth directly.
  • Upgrade planning must also consume the explicit Fabric-owned target-version, compatibility, rollback, and evidence companions directly.
  • Upgrade planning must classify future modules through the Fabric-owned owner-versus-consumer adoption contract directly.
  • Upgrade planning must only consume tool-level directory entries for modules admitted by helpifyr_stack_module_identity_v1.json.
  • Management- and architecture-facing software lists must consume the integrated-system crosswalk instead of widening the narrow stack-tool directory beyond its contract.
  • Downstream consumers must not infer OSS version truth from scattered compose files or stale docs.
  • Floating posture is only allowed where explicitly declared in platform_projection_catalog.json.

OSS Inventory Dashboard​

The platform plane publishes the Gitea-canonical stack inventory through the always-visible Grafana dashboard Helpifyr OSS Inventory & Update Overview at <internal-runtime-redacted>. Its versioned source is deploy/compose/platform-plane/grafana/dashboards/templates/oss-inventory-overview.json.

The read-only observer is defined by contracts/platform/oss_update_observer_contract_v1.json and exposes its Prometheus endpoint on the internal platform network at oss-update-observer:9108. Prometheus pulls it once per hour. Grafana panel refreshes do not trigger public registry calls; they read the last completed Prometheus scrape.

The observer includes only modules admitted by helpifyr_stack_module_identity_v1.json, reads inventory source paths from the central stack_tool_oss_inventory_directory.json, and compares the directory's recorded commit with each repository's current Gitea main commit. It queries only allowlisted public release sources (Docker Hub, Quay, and GitHub releases). Unsupported sources, digest-only/local builds, missing inventories, and failed release lookups remain visible as unknown or a repository gap; they are never converted into a guessed version.

updates_behind is the count of newer stable tags at the precision of the installed tag. For example, a floating 16-alpine tag is compared on the major train, while an exact 16.4 tag is compared at minor/patch precision. The observer performs no update, deployment, Gitea write, or Grafana API mutation.

Admission Rule For New Tools​

Fabric admission is fail-closed for onboarding:

  • contracts/admission/admission_dry_run_input.schema.json
  • contracts/admission/future_tool_admission_governance.json
  • POST /api/v1/tools/admission/dry-run
  • GET /api/v1/contracts/admission-governance

Every new tool that wants to connect to Fabric must provide in docs_metadata:

  • oss_inventory_doc_path = docs/OSS_INVENTORY.md
  • oss_inventory_verify_entrypoint = python scripts/verify_oss_inventory_version_truth.py --check

Missing or mismatched values block admission.

Evidence​

Post verification evidence should be attached to:

  • JaddaHelpifyr/helpifyr-fabric#295

License​