Skip to main content

Operations

Documentation Map​

Operations

Start / Run / Deploy​

Public runtime​

  • build .pages-dist with scripts/build-pages.sh
  • deploy to Cloudflare Pages

Mirrored host runtime​

  • deploy to <internal-runtime-redacted>
  • run Docker Compose stack:
    • jhf-web by default
    • jhf-web-monitor only when the observability profile is explicitly enabled
  • mirrored role: static nginx website runtime, not a second Pages Functions runtime
  • canonical stack contract: contracts/stack-runtime.contract.json plus docs/STACK_RUNTIME_CONTRACT.md
  • canonical runtime-port policy: contracts/runtime-port-policy.contract.json plus docs/RUNTIME_PORT_POLICY.md

Docker healthcheck policy​

ServiceHealthcheckIntervalReason
jhf-webnon/aStatic mirrored website runtime; external verification is sufficient.
jhf-web-monitornon/aExporter-only container; avoid extra probe load.
stripe-clinon/aInteractive helper outside the production runtime path.

Standard mirror start:

docker compose up -d --build
docker compose --profile observability up -d --build

Contract verify:

bash ./scripts/check-stack-runtime.sh
bash ./scripts/check-runtime-guardrails.sh
bash ./scripts/check-stack-runtime.sh --live-host
bash ./scripts/check-runtime-guardrails.sh --live-host
bash ./scripts/check-runtime-port-policy.sh
bash ./scripts/discover-live-ports.sh --live-host

Runtime guardrail defaults:

  • restart/backoff: jhf-web=on-failure:5, jhf-web-monitor=on-failure:3
  • diagnostics: always bounded with timeout, docker logs --since ... --tail ...
  • cleanup/postcheck: no stale docker logs or docker stats readers after deploy/verify

Weaker-host rule:

  • keep only jhf-web in the default runtime path
  • enable jhf-web-monitor only while actively observing metrics
  • keep stripe-cli stopped unless a developer is explicitly testing webhook flows

Healthchecks​

  • /health: minimal liveness/status view for the Pages runtime
  • /ready: minimal readiness view for the Pages runtime
  • /version.json: machine-readable version/update visibility file
  • host-only /nginx_status: operational nginx status for the mirrored runtime

The mirrored host runtime currently exposes the website itself and host-only nginx status, but it does not expose /health, /ready, or /version.json with the same semantics as the public Pages runtime.

Readiness​

Readiness in this repo means:

  • the website runtime can serve public routes
  • the Pages Functions surface is mounted

It does not guarantee:

  • webhook target availability
  • mirrored host health
  • external payment platform status

Logs​

  • local runtime-surface smoke check logs: artifacts/runtime-surfaces.log
  • mirrored host nginx logs: mounted via ./logs:/var/log/nginx
  • standard diagnostics must stay bounded; do not run unbounded streaming log commands in default workflows

Monitoring​

  • CI status from .gitea/workflows/ci.yml
  • optional host exporter on <internal-runtime-redacted>:9113/metrics when the observability profile is enabled
  • Pages health/readiness response checks
  • optional mirror verification via scripts/verify-standalone-openclaw.sh --with-host
  • stack contract + corner-case verification via scripts/check-stack-runtime.sh --live-host --corner-cases
  • deploy drift interpretation from docs/DEPLOY_DRIFT.md (docs/DEPLOY_DRIFT.md)
  • release evidence bundle via scripts/collect-release-evidence.sh
  • versioned deployment package bundle via scripts/package_bundle.sh
  • optional profiles keep helper containers out of the default runtime path

Known Failure Modes​

  • Turnstile secret missing
  • webhook configured but downstream target failing
  • webhook configured with invalid URL or unsupported scheme
  • .pages-dist missing required files
  • runtime surface script failing because wrangler cannot start locally
  • mirror host drift from Gitea main

Restart / Recovery​

  • public runtime: redeploy last known-good Pages artifact
  • mirrored host: rebuild/restart Docker Compose stack
  • deployment package: republish the last known-good package version and re-run download verification
  • optional helpers: enable only when needed and stop again after verification
  • repo verification: rerun all fast checks on Linux-compatible shell
  • post-deploy mirror verification: bash ./scripts/verify-standalone-openclaw.sh --with-host

Runtime Dependencies​

  • Cloudflare Pages
  • Turnstile
  • optional webhook target
  • optional mirrored host runtime

See docs/STANDALONE_OPENCLAW.md (docs/STANDALONE_OPENCLAW.md) for the supported standalone operating profile. See docs/VERIFY.md (docs/VERIFY.md) for the repo-local and optional host verification layers.