# UmamiEdge Production Operations Guide

This guide turns UmamiEdge from a demo package into a controlled global pilot operating model.

## Operating principle

Operate the platform with evidence. Every customer pilot should have:

- a deployment run record
- a Supabase migration record
- a node registration record
- a telemetry validation record
- a customer API-key record
- a routing and SLA evidence trail
- an incident escalation owner

## Required operator pages

- `/status` — global component status
- `/readiness` — go-live gates and owner view
- `/deployments` — deployment run ledger
- `/migrations` — safe SQL execution center
- `/observability` — operational monitoring view
- `/operator` — mission control
- `/network` — topology and corridor view

## Daily checklist

1. Open `/status` and confirm no incident-level components are active.
2. Open `/observability` and review health, routing, energy, and security scores.
3. Open `/incidents` and resolve critical/high incidents before new traffic.
4. Open `/nodes/keys` and confirm no stale or revoked key is still used.
5. Open `/usage` and verify metering totals match API logs.
6. Open `/deployments` and attach evidence to any environment changes.

## SQL upgrade checklist

For an existing Supabase project, run:

1. `docs/database-compatibility-fixes.sql`
2. `docs/supabase-schema.sql`
3. `docs/rls-policies.sql`
4. `docs/seed-demo.sql` only for demo/staging

The compatibility file repairs common older-database failures such as missing columns, enum errors, function parameter metadata conflicts, and `deployment_runs.version` constraints.

## Customer pilot acceptance gates

A customer pilot should not start until:

- OAuth login works
- organization setup works
- at least one site and node exist
- node telemetry is accepted with a valid node key
- invalid telemetry keys are rejected
- `/api/v1/models` returns available model metadata
- routing simulation selects a valid node or explains why none is available
- incidents can be created, acknowledged, and resolved
- compliance evidence artifacts are visible

## Production hardening still required

- Generate real Supabase types from the target project.
- Add real customer API-key enforcement middleware to `/api/v1/*`.
- Connect inference gateway to vLLM, Ollama, TGI, or a managed runtime.
- Add durable queueing for telemetry ingestion.
- Add structured logging and request IDs.
- Add privacy policy, terms, subprocessors, and retention matrix.