Shade/docs/DEPLOYMENT.md

Deploying Shade

Shade ships as a single Docker image that contains the prekey server, observer dashboard, OpenAPI contract, and stale cleanup. You deploy one container per project.

Quick start

docker run -d \
  --name my-project-shade \
  -v my-project-shade:/data \
  -p 3900:3900 \
  -e SHADE_OBSERVER_TOKEN=change-me-to-at-least-16-chars \
  gt.zyon.no/stian/shade-prekey:latest

That's it. Your projects can now register identities and exchange prekey bundles via http://localhost:3900.

Why one container per project

Each project is self-contained. Nova doesn't depend on Orchestrator being up. Future projects can be added without touching existing ones. The container is tiny (~260 MB), idle resource usage is near zero, and each container owns its own SQLite volume.

Project A              Project B              Future projects
─────────              ─────────              ────────────────
app + frontend         app + frontend         app + frontend
    │                      │                      │
    ↓                      ↓                      ↓
shade-a container      shade-b container      shade-n container
(port 3900)            (port 3901)            (port 390n)
sqlite volume          sqlite volume          sqlite volume

Dokploy deployment

1. Go to Dokploy → Projects → New Project → Docker Compose
2. Paste the docker-compose.yml from examples/05-dokploy-deployment
3. Set env vars in the Dokploy UI:
   • SHADE_OBSERVER_TOKEN (generate a random 32+ char string)
4. Set the container name unique per project (e.g., nova-shade, orchestrator-shade)
5. Deploy

Dokploy will pull the image, create the volume, and health check the container automatically.

Volumes and backup

The /data volume holds:

• shade-prekeys.db — the SQLite database with all identities, prekeys, and activity timestamps
• WAL journal files for crash safety

Backup: Copy the .db file while the container is stopped, or use SQLite's online backup API:

docker exec my-project-shade sqlite3 /data/shade-prekeys.db ".backup /data/backup.db"
docker cp my-project-shade:/data/backup.db ./local-backup.db

Restore: Stop the container, copy the .db file into the volume, restart.

PostgreSQL instead of SQLite

If you want to share a Postgres instance (or need HA), set SHADE_PREKEY_PG_URL:

environment:
  - SHADE_PREKEY_PG_URL=postgres://shade:shade@postgres:5432/shade

Tables will be created automatically with the shade_server_* prefix, so they coexist cleanly with any other tables in the same database.

Environment variable reference

Var	Default	Description
PORT	3900	HTTP port
SHADE_PREKEY_DB_PATH	/data/shade-prekeys.db	SQLite file location
SHADE_PREKEY_PG_URL	unset	Postgres URL (overrides SQLite)
SHADE_INBOX_DB_PATH	unset (memory)	SQLite file for the V3.6 inbox relay
SHADE_INBOX_PG_URL	falls back to SHADE_PREKEY_PG_URL	Postgres URL for the inbox relay
SHADE_INBOX_PRUNE_INTERVAL_MINUTES	5	How often expired inbox blobs are dropped
SHADE_OBSERVER_TOKEN	unset	Enables dashboard at /shade-observer/dashboard/. Min 16 chars.
SHADE_STALE_DAYS	30	Purge identities with no activity in N days
SHADE_CLEANUP_INTERVAL_HOURS	24	Cleanup cycle interval
SHADE_LOG_LEVEL	info	debug / info / warn / error
SHADE_OTEL_ENABLED	unset	Set to 1/true to enable OpenTelemetry tracing on withTracer()-configured deployments. See observability.md.
SHADE_DISABLE_RATE_LIMIT	unset	Set to 1 to disable IP rate-limits on every prekey + inbox route. Single-tenant deployments only — multi-tenant relays must leave this unset to keep the abuse defenses on.

Health and observability

• Health: GET /health — returns {"status":"ok"} when the storage backend is reachable. Docker's HEALTHCHECK uses this.
• Metrics: GET /metrics — Prometheus format with counters, histograms, and gauges for all routes.
• Tracing: Optional OpenTelemetry spans via @shade/observability. Off by default; flip SHADE_OTEL_ENABLED=1 to activate. PII-safe span attributes are documented in observability.md.
• OpenAPI: GET /openapi.yaml — machine-readable API contract for any language.
• Redoc viewer: GET /docs — human-readable API reference.
• Dashboard: GET /shade-observer/dashboard/ — live activity viewer (requires token).

Stale cleanup

Identities with no activity (no bundle fetches, no replenishments, no registration refreshes) for more than SHADE_STALE_DAYS days are automatically purged from the database. This keeps the database bounded without manual housekeeping.

The cleanup task runs once at startup and then every SHADE_CLEANUP_INTERVAL_HOURS hours. Each cycle logs the number of purged identities.

Multiple Shade instances on the same host

Run multiple projects side-by-side with different container names and ports:

services:
  nova-shade:
    container_name: nova-shade
    image: gt.zyon.no/stian/shade-prekey:latest
    ports: ["3900:3900"]
    volumes: [nova-shade-data:/data]
    environment:
      - SHADE_OBSERVER_TOKEN=nova-token-32-chars-minimum-xxx

  orch-shade:
    container_name: orch-shade
    image: gt.zyon.no/stian/shade-prekey:latest
    ports: ["3901:3900"]
    volumes: [orch-shade-data:/data]
    environment:
      - SHADE_OBSERVER_TOKEN=orch-token-32-chars-minimum-xxx

volumes:
  nova-shade-data:
  orch-shade-data:

CI publishing

Tagged releases auto-publish to the Gitea container registry via .gitea/workflows/docker.yml. To cut a release:

bun run version 1.0.1
git push --tags

Security notes

• Never commit SHADE_OBSERVER_TOKEN. Use Dokploy secrets or environment-specific .env files.
• The prekey server stores public keys only. No private keys ever touch it.
• Rate limiting is on by default (5 registrations per hour per IP, etc.). Tune via createPrekeyRoutes options if embedding, or configure at reverse-proxy level for the container.
• Put the container behind a reverse proxy (Traefik, Caddy) for TLS termination.