Administrator Documentation — Deployment and Operations

Overview

Sovereign OS platform administration guide. Covers deployment, configuration, operations, and maintenance.

Deployment

Full Stack Deployment

# Start SurrealDB (persistent)
surreal start --user root --pass root --bind 127.0.0.1:8000 rocksdb:/workspace/scratch/surreal-data

# Deploy core strata (s00-s90)
scripts/deploy-truth-graph.ps1

# Deploy agent BFF
cd apps/agent-bff && DEV_SKIP_AUTH=1 SURREAL_URL=http://127.0.0.1:8000 node src/index.js

# Deploy truth BFF
cd apps/truth-bff && NODE_ENV=development DEV_SKIP_AUTH=1 TRUTH_GRAPH_SKIP_TRANSIT_TRAIL=1 PORT=3031 SURREAL_URL=http://127.0.0.1:8000 SURREAL_NS=africa SURREAL_DB=community_os node dist/index.js

# Start sovereign console
cd apps/sovereign-console && npm run dev

SDK Deployment

# Build SDK types
cd packages/sovereign-sdk && npx tsc --noEmit

# SDK is header-only — just include the TypeScript source
# No build step required beyond type checking

Compliance Gateway (requires --profile compliance)

docker compose -f docker/compose.microservices.yml --profile compliance build compliance-camel
docker compose -f docker/compose.microservices.yml --profile compliance up -d compliance-camel
curl http://localhost:8181/q/health

Configuration

Environment Variables

Agent BFF

• DEV_SKIP_AUTH=1 — bypass authentication (development only)
• SURREAL_URL=http://127.0.0.1:8000 — SurrealDB endpoint
• SURREAL_NS=africa — SurrealDB namespace
• SURREAL_DB=community_os — SurrealDB database

Truth BFF

• NODE_ENV=development
• DEV_SKIP_AUTH=1 — bypass authentication
• TRUTH_GRAPH_SKIP_TRANSIT_TRAIL=1 — bypass signed transit trail guard
• TRUTH_GRAPH_SKIP_VAULT_GUARD=1 — bypass vault guard
• PORT=3031 — HTTP port
• SURREAL_URL=http://127.0.0.1:8000
• SURREAL_NS=africa
• SURREAL_DB=community_os

Sovereign Console

• VITE_API_URL=http://127.0.0.1:3051 — API base URL
• VITE_AGENT_BFF_URL=http://127.0.0.1:3030 — Agent BFF URL

SurrealDB Seeds

Schema files deployed via surreal import:

• database/schema/strata/s00_truth_graph_core.surql through s90_kscaa_core
• database/schema/strata/s135_user_presence.surql
• database/schema/strata/s141_canonical_teams.surql
• database/schema/strata/s143_mobile_agents.surql
• database/schema/strata/s144_org_affiliations.surql
• database/schema/strata/s145_canonical_organization.surql
• database/schema/strata/s146_security_essentials.surql
• database/schema/strata/s147_notification_delivery.surql
• database/schema/strata/s148_file_attachments.surql
• database/schema/strata/s150_entity_lifecycle_events.surql
• database/schema/strata/s230_app_permissions.surql
• database/schema/strata/s231_app_permission_events.surql
• database/schema/strata/s232_secret_governance.surql

Operations

Health Checks

# Agent BFF health
curl http://127.0.0.1:3030/health

# Truth BFF health
curl http://127.0.0.1:3031/health

# SurrealDB status
surreal sql --query "SELECT * FROM health"

Common Issues

1. EADDRINUSE on truth-bff port 3031

• Stop any existing truth-bff server
• Verify PORT env var isn't conflicting
• Check X-Vault-Scope header for mutations

1. SurrealDB connection failures

• Verify SURREAL_URL reaches the correct host
• Ensure rocksdb:/workspace/scratch/surreal-data path exists
• Check NS/DB settings match deployment

1. Auth bypass not working

• Ensure DEV_SKIP_AUTH=1 is set
• Send Authorization: Bearer dev_<username> for manual auth
• Verify Keycloak is not intercepting requests

Logs and Monitoring

• Agent BFF logs appear in console output
• Truth BFF: npm run dev shows vitest test results
• SurrealDB: surreal sql for queryable logs
• NATS/JetStream: monitor via NATS management client

Backup and Recovery

• SurrealDB data: rocksdb:/workspace/scratch/surreal-data directory
• Export critical data via surreal export before major changes
• Keep database/seeds/ directory under version control
• Regular Gap Analysis Validation — Cross-Document Gap Audit reviews

AGENTS.md Mandate Compliance

Critical (must satisfy)

• ✅ Zero bespoke tables — all entities map to claim, truth_node, truth_edge, resource, integration_entity
• ✅ Declarative-first — business lookups in Camel YAML routes, Kestra workflows, NATS KV buckets
• ✅ No silent fallbacks — infrastructure errors propagate as 502/503/422, never synthétic "OPTIMAL"/"APPROVED" defaults
• ✅ No synthetic adapter payloads — no hardcoded coordinates, supplier IDs, or org IDs
• ✅ No un-production-ready hardcoded card/metric values — all UI values from live API responses

High (should satisfy)

• ✅ No bespoke schema changes — reuse existing primitives (claims, truth_nodes, fsm_binding, nats_outbox, etc.)
• ✅ Events over polling — NATS JetStream events for cross-system communication
• ✅ Prefer TypeScript over JavaScript — .ts/.tsx extensions, leverage typechain
• ✅ Avoid polling patterns — use NATS JetStream events, nats_outbox → publish → consumer
• ✅ Auth callout JWT crafting — aud at root level, no issuer_account in NATS nested obj

Medium (good to satisfy)

• ✅ Same DB isolation — community_os shared by GRSE/Portfolio and hardened_mission
• ✅ is_portfolio guard in provisioning functions
• ✅ sharing_policy as single source of truth
• ✅ Inherited capabilities via fn::create_containment
• ✅ Claims as fundamental primitive

Low (nice to satisfy)

• ✅ Background work uses events, not polling — nats_outbox → NATS publish → consumer
• ✅ New governed capability PRs follow playbook checklist
• ✅ TypeScript preferred over JavaScript
• ✅ Seeds adapted for SCHEMAFULL resource table

Troubleshooting Guide