@shade/server (0.1.1)
Installation
@shade:registry=npm install @shade/server@0.1.1"@shade/server": "0.1.1"About this package
@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 checkhttp://localhost:3900/openapi.yaml— API contract for any languagehttp://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.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @shade/core | ^0.1.1 |
| hono | ^4.12.12 |
Development Dependencies
| ID | Version |
|---|---|
| @shade/crypto-web | workspace:* |
Optional Dependencies
| ID | Version |
|---|---|
| @shade/crypto-web | ^0.1.1 |
| @shade/observer | ^0.1.1 |
| @shade/storage-postgres | ^0.1.1 |
| @shade/storage-sqlite | ^0.1.1 |