Files

Test / test (push) Has been cancelled

Details

feat(container): M-Box 1-8 — stack-agnostic standalone Docker container

Shade now ships as a self-contained Docker image. Deploy one container
per project, any stack (Bun, Python, Go, Rust, Kotlin) can talk to it via
plain HTTP. Zero coupling to consumer codebases.

M-Box 1: Stale identity cleanup API
- touchIdentity + purgeStaleIdentities on PrekeyStore interface
- Implemented for Memory, SQLite, and Postgres backends
- SQLite adds last_activity_at column with migration ALTER for existing DBs
- Postgres adds the same via raw SQL with IF NOT EXISTS guards
- Routes call touchIdentity on register, bundle fetch, replenish
- 4 new tests for the cleanup API

M-Box 2: Stale cleanup background task
- StaleCleanupTask runs purge on startup + every 24h (configurable)
- Reads SHADE_STALE_DAYS (default 30) and SHADE_CLEANUP_INTERVAL_HOURS
- Wired into standalone.ts, stopped on graceful shutdown
- 5 new tests for the task

M-Box 3: Observer baked into the container
- standalone.ts conditionally mounts @shade/observer at /shade-observer
  when SHADE_OBSERVER_TOKEN is set (and >= 16 chars)
- Shared PrekeyServerEvents emitter feeds both routes and observer
- @shade/observer added as optional dependency of @shade/server

M-Box 4: Dockerfile with dashboard build
- Multi-stage build: oven/bun:1 builder → oven/bun:1-alpine runtime
- COPY packages/ wholesale so workspace lockfile resolves cleanly
- RUN bun run build inside shade-dashboard → dist/ → observer/dist/
- Non-root shade user, /data volume, healthcheck, env defaults
- Final image: 260 MB

M-Box 5: OpenAPI spec for stack-agnostic clients
- packages/shade-server/openapi.yaml documents all 9 endpoints with
  request/response schemas, security (Ed25519 signatures + bearer token)
- createOpenApiRoutes serves /openapi.yaml and /docs (Redoc viewer)
- Any language can generate a client with openapi-generator

M-Box 6: Docker CI pipeline
- .gitea/workflows/docker.yml builds + pushes on git tag v*
- scripts/build-docker.ts for local builds, supports --push with GITEA_TOKEN
- Root package.json: build:docker, publish:docker scripts

M-Box 7: Deployment documentation
- packages/shade-server/README rewritten: 5-line quickstart with the image
- docs/DEPLOYMENT.md: full reference, env vars, backup, Dokploy, PG setup
- examples/05-dokploy-deployment/docker-compose.yml updated to pull
  published image (gt.zyon.no/stian/shade-prekey:latest)
- Root README deployment section rewritten

M-Box 8: End-to-end verification
- Image builds locally (bun run build:docker)
- /health, /openapi.yaml, /docs, /metrics, /shade-observer all respond
- 401 without observer token, 200 with
- Real SDK client round-trip: Alice → container → Bob → reply → Alice
- Persistence: identity + prekeys survive container restart (count 20→18
  as expected from two bundle fetches)

285 tests passing, 0 failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-11 14:29:00 +02:00

3.7 KiB

Raw Blame History

@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.

3.7 KiB Raw Blame History