Runbook

Use this page for restart steps, migration order, smoke checks, and basic incident handling around the Emban API.

Scope: this is the operational companion to Alpha Readiness. Use it when you need to start, validate, or recover the running system rather than reason about product concepts.

Operations map

These four pages cover the release and runtime surface from deployment through validation.

Gate Alpha Readiness Use the release checklist and stop-ship rules before external demos or onboarding. Ops Runbook Use the current migration order, smoke checks, and restart steps for a live system. Reference API Reference Confirm payload shapes, auth semantics, and runtime commands against the current server. Proof Live demo Validate the public signed-session path, runtime events, and host commands against seeded data.

Starting the server

cd /var/www/emban
source .env
./emban

The server listens on SERVER_PORT with 8092 as the default. PostgreSQL and ClickHouse must already be reachable.

Infrastructure

Service	Runtime	Port
PostgreSQL	`emban_postgres`	`5434`
ClickHouse	external	`9000`
Redis	`emban_redis`	`6380`
Emban API	native binary	`8092`
Builder	native	`3003`
Demo	native or static	`3002`

Migrations

Run the full chain in order on a fresh database:

psql $DATABASE_URL -f migrations/001_init.sql
psql $DATABASE_URL -f migrations/002_billing.sql
psql $DATABASE_URL -f migrations/003_auth.sql
psql $DATABASE_URL -f migrations/004_invites_publish.sql
psql $DATABASE_URL -f migrations/005_entitlements.sql
psql $DATABASE_URL -f migrations/006_alerts.sql

All migrations are idempotent and safe to re-run.

Prelaunch smoke

# Full local flow
bash scripts/prelaunch_smoke.sh

# Against a live base URL
bash scripts/prelaunch_smoke.sh https://emban.sidelabs.dev

# Static-only validation when the server is intentionally down
bash scripts/prelaunch_smoke.sh --skip-e2e

The script covers Go build, app and demo static validation, embed SDK checks, and the full API happy path when the server is reachable.

Backup

PostgreSQL

# Backup
docker exec emban_postgres pg_dump -U emban emban > backup_pg_$(date +%Y%m%d).sql

# Restore
docker exec -i emban_postgres psql -U emban emban < backup_pg_YYYYMMDD.sql

ClickHouse

# Backup events table
clickhouse-client --host=159.69.6.132 --user=poptrade --password=XXX \
  --database=emban --query="SELECT * FROM events FORMAT Native" > events_backup.native

# Restore
clickhouse-client --host=159.69.6.132 --user=poptrade --password=XXX \
  --database=emban --query="INSERT INTO events FORMAT Native" < events_backup.native

Health and monitoring

Health: GET /health returns {"status":"ok"}
Metrics: GET /metrics returns Prometheus-format metrics
Audit: GET /v1/audit returns recent actions for authenticated admin or owner access
Public live-demo session: GET /v1/demo/embed-url?tenant_id=demo_workspace returns a seeded signed session for the website demo

*/5 * * * * curl -sf http://localhost:8092/health || echo "Emban down" | mail -s "ALERT" ops@example.com

Session cleanup

Expired embed sessions are cleaned automatically every hour by a background goroutine. No manual cleanup is normally required.

Common issues

Symptom	Likely cause	Fix
Server refuses to start with a JWT secret error	Default or missing JWT secret	Set `JWT_SECRET` in `.env` to a real random value such as `openssl rand -hex 32`.
CORS errors in the browser	Origin not in allowlist	Add the real app origins to `CORS_ORIGINS`.
`dashboard not published` during embed	The dashboard is still draft-only	Publish it in the builder or via `POST /v1/dashboards/{id}/publish`.
Empty dashboard right after registration	Seed still running	Wait a few seconds and refresh. Seed is asynchronous.
Live demo page loads but cannot fetch a session	Demo endpoint unavailable or stale backend binary	Confirm `GET /v1/demo/embed-url` returns `200` on the live API and restart the API if needed.
Unexpected `402` responses	Plan limit or entitlement gate	Check the response body for `code`, `plan`, `upgrade_to`, `limit`, and `used`.

Restarting

# Rebuild Go + embed + app + demo
./restart.sh --all

# Find process
pgrep emban

# Graceful stop
pkill emban

# Start
cd /var/www/emban && nohup ./emban > /tmp/emban.log 2>&1 &

# Verify
curl http://localhost:8092/health

Related docs

Alpha Readiness — release gate, stop-ship issues, and first-week metrics
API Reference — auth semantics, payload shapes, and runtime contract
Quickstart How It Works — canonical first-event to live-embed flow