Ops Hub Bootstrap Runbook

Date: 2026-06-14

Purpose

This runbook gives the operator-ready bootstrap path for ops-hub, the VSM Operations / System 1 extension of Inter-Hub.

Use this when an authenticated Inter-Hub admin session or deployment migration is available. The current public v2 API is not sufficient to create the hub, manifest, API consumer, API key, or seed widgets by itself.

As of 2026-06-06, implementation work for ops-hub belongs in the dedicated repo at /home/worsch/ops-hub with remote gitea-remote:coulomb/ops-hub.git. This runbook remains a HelixForge bootstrap handoff reference until the implementation repo ports or supersedes it.

Inputs

Manifest draft: wiki/ops-hub-manifest.draft.json
Widget seed: wiki/ops-hub-widgets.seed.json
Migration fallback: wiki/ops-hub-bootstrap.sql
Implementation repo: /home/worsch/ops-hub

Current Bootstrap Decision

Prefer the supported Inter-Hub bootstrap API once production exposes the current API surface. Do not proceed with manual DB seeding unless the operator explicitly chooses that fallback. Until the production API gate passes, the authenticated Inter-Hub admin UI and SQL migration remain fallback paths for attended operator use only.

Production API gate:

https://hub.coulomb.social/api/v2/hubs returns 401 unauthenticated, not 404.
OpenAPI lists /hubs, /hub-capability-manifests, /api-consumers, and /policy-scopes.
After the gate passes, run the supported bootstrap/smoke path from the relevant inter-hub or ops-hub tooling with IHUB_BASE and an operator key.

Latest check, 2026-06-14:

ops-hub/scripts/interhub-gate-probe.py still reports the production gate closed.
GET /api/v2/hubs returns 404.
Live OpenAPI still omits /hubs, /hub-capability-manifests, /api-consumers, and /policy-scopes.
Do not run the preferred API bootstrap path until the current Inter-Hub API is deployed, unless the operator explicitly chooses the SQL fallback.

VSM classification is stored in the manifest capability description for now:

hub_family: vsm
vsm_function: OPS
vsm_system: S1

Newer Inter-Hub schemas have first-class hub metadata columns for these values. The SQL fallback sets those columns when present and still carries the same classification in the manifest description for older deployments.

As of the 2026-05-19 access check, the workstation kubeconfig only points at CoulombCore (92.205.130.254) and does not include the Railiance01 (92.205.62.239) cluster where hub.coulomb.social resolves. SSH key access to root, worsch, and ubuntu on Railiance01 was denied, so the SQL fallback must be run from a host/session that already has Railiance01 cluster access.

UI Path

Log in to Inter-Hub at https://hub.coulomb.social/NewSession.
Open /Hubs/new.
Create the hub:
- Name: Ops Hub
- Slug: ops-hub
- Domain: ops.coulomb.social
- Kind: domain
Open /HubCapabilityManifests/new?hubId=<ops-hub-id>.
Create a draft manifest with:
- Version: 1.0
- Capability description from wiki/ops-hub-manifest.draft.json
- Contact: operator/team contact
Edit the manifest and copy in:
- declaredWidgetTypes
- declaredEventTypes
- declaredAnnotationCategories
- declaredPolicyScopes
Activate the manifest.
Open /ApiConsumers/new.
Create an API consumer bound to the active ops manifest:
- Name: ops-hub
- Description: API consumer for the VSM Operations hub
- Scopes for the key: framework:read hub:ops-hub:read hub:ops-hub:write
Generate an API key and store it only in the operator secret store or local environment. Do not commit it to Git.
Seed the widgets from wiki/ops-hub-widgets.seed.json through the UI or migration fallback.

SQL Fallback Path

From a shell with Railiance01 Kubernetes access, run:

kubectl exec -i -n databases net-kingdom-pg-1 -- \
  psql -U postgres -d interhub \
  < /home/worsch/helix-forge/wiki/ops-hub-bootstrap.sql

If using the HostEurope kubeconfig from the workstation, first restore ~/.kube/config-hosteurope as documented by railiance-cluster, then run:

KUBECONFIG=~/.kube/config-hosteurope \
kubectl exec -i -n databases net-kingdom-pg-1 -- \
  psql -U postgres -d interhub \
  < /home/worsch/helix-forge/wiki/ops-hub-bootstrap.sql

The SQL fallback creates the hub, active manifest, registry entries, API consumer row, and seed widgets. It does not create the one-time visible static API key; generate that in the authenticated Inter-Hub UI and store it outside Git.

Validation

After manifest activation:

curl -s https://hub.coulomb.social/api/v2/widget-types
curl -s https://hub.coulomb.social/api/v2/event-types
curl -s https://hub.coulomb.social/api/v2/annotation-categories

Expected: ops-owned vocabulary appears in the relevant registries.

After API key creation:

curl -s -X POST https://hub.coulomb.social/api/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<api-consumer-id>" \
  --data-urlencode "client_secret=<static-api-key>" \
  --data-urlencode "scope=framework:read hub:ops-hub:read hub:ops-hub:write"

Expected: a short-lived access token is returned.

After widget seeding:

curl -s https://hub.coulomb.social/api/v2/hub-registry

Expected: ops-hub is visible, and the operator can see the seeded widgets in the authenticated UI.

Known Blockers

The live public v2 API has no POST /api/v2/hubs.
The live public v2 API has no POST /api/v2/widgets.
There are no v2 endpoints for manifest creation/activation.
There are no v2 endpoints for API consumer or key creation.
There is no /api/v2/policy-scopes.
Interaction event create currently does not persist submitted metadata.
Webhook dispatch currently uses the hard-coded "clicked" event type.

These are tracked by HF-WP-0001 T10 for Inter-Hub hardening.

5.9 KiB Raw Blame History