generated from coulomb/repo-seed
109 lines
3.4 KiB
Markdown
109 lines
3.4 KiB
Markdown
# 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`
|
|
|
|
Inter-Hub does not yet have first-class hub metadata columns for these values.
|
|
|
|
## 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.
|
|
|
|
## Validation
|
|
|
|
After manifest activation:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|