helix-forge/wiki/OpsHubBootstrapRunbook.md

Ops Hub Bootstrap Runbook

Date: 2026-05-16

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.

Inputs

• Manifest draft: wiki/ops-hub-manifest.draft.json
• Widget seed: wiki/ops-hub-widgets.seed.json
• Migration fallback: wiki/ops-hub-bootstrap.sql

Current Bootstrap Decision

Use the authenticated Inter-Hub admin UI first. Use the SQL migration fallback only when a repeatable deployment-side bootstrap is needed before the v2 API is hardened.

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

1. Log in to Inter-Hub at https://hub.coulomb.social/NewSession.
2. Open /Hubs/new.
3. Create the hub:
   • Name: Ops Hub
   • Slug: ops-hub
   • Domain: ops.coulomb.social
   • Kind: domain
4. Open /HubCapabilityManifests/new?hubId=<ops-hub-id>.
5. Create a draft manifest with:
   • Version: 1.0
   • Capability description from wiki/ops-hub-manifest.draft.json
   • Contact: operator/team contact
6. Edit the manifest and copy in:
   • declaredWidgetTypes
   • declaredEventTypes
   • declaredAnnotationCategories
   • declaredPolicyScopes
7. Activate the manifest.
8. Open /ApiConsumers/new.
9. 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
10. Generate an API key and store it only in the operator secret store or local environment. Do not commit it to Git.
11. 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.