Skip to main content

Install and Run Helpifyr

Use this page when you need the first safe deployment path for a Helpifyr environment and want an operator-grade verify path instead of a repo-by-repo install tour.

When to use this page​

  • You are evaluating whether the current stack is already installed correctly.
  • You are preparing a first controlled deployment or redeploy.
  • You need the minimum cross-repo checks before handing the stack to operators or implementers.

Prerequisites​

  • You have the owner-approved stack inputs for the environment you are preparing.
  • You know which runtime owner is responsible for the target environment.
  • You can read the public-safe Fabric verification surfaces.
  • You can run repo-owned verification commands from the owning workspace when runtime truth and repo truth must be compared.

What this page covers​

  • the minimum install flow
  • the first health and readiness readback
  • the handoff between docs truth, repo truth, and runtime truth
  • the first escalation points when install verification fails

Architecture / Flow​

Step-by-step procedure​

1. Confirm the reader journey and ownership boundary​

Before you install anything, confirm that you are following the correct owner lane:

  • helpifyr-fabric owns the docs-platform, readiness, and cross-stack governance truth.
  • jhf-docs owns the committed reviewable materialized docs workspace.
  • jhf-web owns the main-site alias and shell consumer path for public docs.
  • runtime-specific installation and recovery steps still belong to the owning runtime repos and deployment lanes.

If the required step would mutate a running host, stop and use the owner runbook rather than inventing a local shortcut.

2. Read the docs-platform posture first​

Use the docs surfaces to confirm what the public docs system believes is current:

GET /api/v1/docs/platform
GET /api/v1/docs/catalog
GET /api/v1/docs/readiness

These calls answer different questions:

  • /api/v1/docs/platform: docs contract, rollout posture, and platform-level rules
  • /api/v1/docs/catalog: what the platform currently exposes as docs truth
  • /api/v1/docs/readiness: whether the docs system believes the current rollout is fit for consumption

3. Record the first runtime baseline​

Before you treat an install as done, read the stack health surfaces that operators will rely on later:

GET /health
GET /api/v1/platform/services
GET /api/v1/observability/readiness
GET /api/v1/security/readiness

This establishes:

  • coarse service availability
  • subsystem-aware readiness
  • security-readiness posture

4. Compare repo truth with running truth when needed​

If the runtime reads back differently from the expected stack shape, use the repo-owned verifier instead of ad-hoc host inspection first:

python ./scripts/verify_runtime_materialization.py --check

Use this when:

  • API readiness looks stale
  • the runtime topology does not match expected deployment truth
  • a service appears present but not correctly materialized

5. Hand off to operations after the first green pass​

An install is only ready for the next reader if:

  • docs-platform readiness is green enough for the environment
  • health and readiness checks are consistent
  • repo truth and runtime truth do not show obvious drift
  • the operator has a clear next path into monitoring and troubleshooting

The next pages are usually:

Example verification session​

This is an illustrative public-safe sequence for the first verification pass:

curl -s <fabric-base-url>/api/v1/docs/platform
curl -s <fabric-base-url>/api/v1/docs/catalog
curl -s <fabric-base-url>/api/v1/docs/readiness
curl -s <fabric-base-url>/health
curl -s <fabric-base-url>/api/v1/platform/services
curl -s <fabric-base-url>/api/v1/observability/readiness
curl -s <fabric-base-url>/api/v1/security/readiness
python ./scripts/verify_runtime_materialization.py --check

Expected outcome:

  • the docs surfaces are readable
  • the stack-level health surfaces are internally consistent
  • the materialization verifier does not show obvious repo-vs-runtime drift

Verification​

The first install path is considered complete only when all of the following are true:

  1. GET /api/v1/docs/platform succeeds.
  2. GET /api/v1/docs/catalog succeeds.
  3. GET /api/v1/docs/readiness does not contradict the current rollout state.
  4. GET /health and GET /api/v1/platform/services are readable for the environment.
  5. GET /api/v1/observability/readiness and GET /api/v1/security/readiness do not expose an unresolved blocker for the install path.
  6. python ./scripts/verify_runtime_materialization.py --check does not prove repo/runtime drift that still needs remediation.

Common failure modes​

Docs look current but runtime is not aligned​

Likely meaning:

  • docs truth was refreshed, but the running stack was not.

Next action:

  • run python ./scripts/verify_runtime_materialization.py --check
  • then move to Check stack health

Health is green but readiness is not​

Likely meaning:

  • the services answer, but one subsystem still fails the deeper contract posture.

Next action:

  • inspect GET /api/v1/observability/readiness
  • inspect GET /api/v1/security/readiness

Install appears complete but Fabric readiness is inconsistent​

Likely meaning:

  • this is now a bounded Fabric-owned troubleshooting case.

Next action:

Owner Handoff​

  • docs-platform truth owner: JaddaHelpifyr/helpifyr-fabric
  • materialized docs workspace owner: JaddaHelpifyr/jhf-docs
  • live docs publisher owner: JaddaHelpifyr/jhf-docs
  • main-site alias and shell consumer owner: JaddaHelpifyr/jhf-web
  • runtime installation and recovery owner: the repo that owns the deployed stack surface

Source Truth​

Next paths​