Skip to main content

Operations

Documentation Map​

Operations

Start / Run / Deploy​

  • production stack contract: infra/docker/docker-compose.stack.yml
  • test stack contract: infra/docker/docker-compose.test.yml
  • workflow reconcile path: bash scripts/import_workflows.sh

Healthchecks​

  • n8n: ${N8N_BASE_URL}/healthz
  • ERiC: ${ERIC_HEALTHCHECK_URL}/health and require eric_available=true when the field is present

Readiness​

  • canonical readiness signal:
bash scripts/check_runtime_readiness.sh
  • combined operator signal:
bash scripts/check_stack_state.sh
  • stack ownership-only signal:
bash scripts/check_stack_ownership.sh
  • stack/runtime contract signal:
bash scripts/check_stack_runtime_contract.sh
bash scripts/check_stack_runtime_contract.sh --live
python scripts/check_runtime_materialization_drift.py
python scripts/check_runtime_materialization_drift.py --live
bash scripts/materialize_eric_runtime.sh --cert-source <path-to-elster-pfx>
python scripts/check_elster_artifact_readiness.py --vendor-root <local-elster-drop> --live
python scripts/export_live_port_observation.py --output artifacts/live-port-observation.json

There is still no dedicated HTTP readiness endpoint; this remains a documented gap.

Logs​

  • n8n execution logs (bounded only via bash scripts/safe_docker_logs.sh jhf-wire-n8n)
  • ERiC service logs (bounded only via bash scripts/safe_docker_logs.sh jhf-wire-eric)
  • provider responses surfaced through workflow execution details
  • policy reference: docs/HOST_DOCKER_LOG_GUARDRAILS.md

Monitoring​

Today:

  • CI status in Gitea
  • operator scripts for readiness and smoke
  • probe script for finAPI
  • repeatable runtime load snapshot script:
    • bash scripts/capture_runtime_load_snapshot.sh <output.json>

Still missing:

  • standardized metrics endpoint
  • dashboard-fed publication of the Fabric metadata export

Alerts And Dashboard Signals​

Operator-relevant alerts:

  • callback failures to Helpifyr Spindle, especially callback target reachability and TLS trust mismatches
  • readiness state drops from ready to pending
  • provider auth failures
  • workflow import drift between Git and n8n

Useful dashboard signals:

  • latest verified Git commit
  • current CI state on Gitea
  • readiness summary by dependency key
  • health surface reachability for n8n and ERiC
  • explicit ERiC binary availability signal from /health
  • explicit ERiC runtime split from /health: eric_runtime_available vs. eric_submit_available
  • last successful finAPI live probe time
  • count of callback failures by workflow

Non-HTTP Status Contracts​

  • Readiness is currently exposed only through:
    • bash scripts/check_runtime_readiness.sh
    • bash scripts/check_stack_state.sh
    • bash scripts/check_stack_runtime_contract.sh
    • python scripts/check_runtime_materialization_drift.py
  • Combined machine-readable status is currently exposed only through:
    • python scripts/export-fabric-metadata.py --pretty
  • Controlled live host-port publication for consumers is exposed through:
    • python scripts/export_live_port_observation.py --output artifacts/live-port-observation.json
  • Support-case delivery evidence and corner-case recovery posture are exposed through:
    • python scripts/validate_support_case_delivery.py --pretty
    • bash scripts/check_support_case_delivery.sh
  • Metrics have no equivalent contract yet; this is still a real gap.

Known Error Shapes​

  • provider-side domain errors from finAPI VoP / IBAN Name Check
  • callback endpoint mismatch or TLS trust failure (bash scripts/check_callback_target.sh)
  • pending credentials causing readiness pending
  • ERiC health reachable but eric_available=false
  • ERiC runtime libraries present but eric_submit_available=false
  • ERiC runtime inventory helper confirms missing runtime assets or wrong adapter paths: bash scripts/check_eric_runtime_inventory.sh
  • host restore/drift removed jhf-wire_eric_runtime; rematerialize with bash scripts/materialize_eric_runtime.sh --cert-source <path-to-elster-pfx> and rerun runtime checks
  • ELSTER vendor drop and cert-path materialization verifier: python scripts/check_elster_artifact_readiness.py --vendor-root <local-elster-drop> --live
  • support notification retry/recovery posture is validated via scripts/validate_support_case_delivery.py
  • compliance runtime issues are tracked in jhf-selvage (moved scope)

Restart / Recovery Hints​

  • repair in Git first
  • redeploy only stack-owned services
  • re-import workflows
  • re-run readiness and smoke checks

Runtime Dependencies​

  • Docker standalone runtime on <internal-runtime-redacted>
  • n8n
  • ERiC service
  • provider credentials and network reachability

External Blockers​

  • external and operator-owned blockers are tracked in docs/EXTERNAL_BLOCKER_MATRIX.md
  • matching Gitea external/operator issues are currently #1, #2, #3, #5, and #45

License: AGPLv3 Project website: https://helpifyr.com