Sterister
7e0f7320a9
Some checks failed
Test / test (push) Has been cancelled
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>
91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
# @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
|
|
|
|
```bash
|
|
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](./openapi.yaml) for the full contract.
|
|
|
|
**TypeScript / Bun:**
|
|
```ts
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`.
|