Shade/packages/shade-server

@shade/server — Shade Prekey Server (standalone container)

A self-contained Docker image that provides the prekey server, OpenAPI contract, observer dashboard, and stale cleanup — everything a project needs to adopt Shade, with zero coupling to the consumer's stack.

Deploy in 2 minutes

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

Done. Your prekey server is live:

• http://localhost:3900/health — health check
• http://localhost:3900/openapi.yaml — API contract for any language
• http://localhost:3900/docs — interactive API reference (Redoc)
• http://localhost:3900/shade-observer/dashboard/ — live debugger (token required)
• http://localhost:3900/v1/keys/* — prekey REST API

Your consumer projects (Nova, Orchestrator, Python apps, anything) then point at http://localhost:3900 as their prekeyServer URL.

One container per project

The recommended architecture is one Shade container per project:

nova-shade          (Docker container, SQLite volume)    ← Nova backend + Android app
orchestrator-shade  (Docker container, SQLite volume)    ← Orchestrator hub + workstations
future-project     (Docker container, SQLite volume)    ← Any future app

Each project owns its own container, its own volume, its own observer token. Zero cross-project coupling. If one project's Shade is down, the others keep running.

Environment variables

Var	Default	Description
PORT	3900	HTTP port
SHADE_PREKEY_DB_PATH	/data/shade-prekeys.db	SQLite file path
SHADE_PREKEY_PG_URL	unset	Postgres connection string. If set, overrides SQLite.
SHADE_OBSERVER_TOKEN	unset	Bearer token for the dashboard. Min 16 chars. Unset = observer disabled.
SHADE_STALE_DAYS	30	Purge identities with no activity in N days
SHADE_CLEANUP_INTERVAL_HOURS	24	How often the cleanup task runs
SHADE_LOG_LEVEL	info	debug / info / warn / error

Persistence

The /data volume holds the SQLite database. Back it up by copying the .db file (use SQLite's online backup API or just stop the container briefly).

To switch to Postgres, set SHADE_PREKEY_PG_URL=postgres://user:pass@host/db. Tables will be created automatically with the shade_server_* prefix.

Stale cleanup

Identities that have no activity (no bundle fetches, no replenishments, no registration updates) for more than SHADE_STALE_DAYS days are automatically purged. This keeps the database bounded even if users never unregister cleanly.

Using from your project

Any language can speak to a Shade container — it's just HTTP. See openapi.yaml for the full contract.

TypeScript / Bun:

import { createShade } from '@shade/sdk';
const shade = await createShade({ prekeyServer: 'http://my-project-shade:3900' });

Python / Go / Rust: generate a client from the OpenAPI spec with openapi-generator, or implement the wire protocol directly (8 endpoints, Ed25519 signatures documented in the spec).

Android: use the shade-android Kotlin module. Same wire protocol, verified by cross-platform test vectors.

Building locally

bun run build:docker                          # build shade-prekey:dev
bun run build:docker -- --tag v1.0.0          # custom tag
GITEA_TOKEN=... bun run publish:docker        # build + push to registry

CI publishing

Tag a release and CI publishes automatically:

git tag v1.0.0
git push --tags

.gitea/workflows/docker.yml runs tests, builds the image, and pushes both v1.0.0 and latest tags to gt.zyon.no/stian/shade-prekey.