Sterister
680d6386f3
Plumbing fix only — both createPrekeyRoutes and createInboxRoutes already accepted disableRateLimit; standalone.ts just didn't read the env. Now SHADE_DISABLE_RATE_LIMIT=1 turns off IP rate-limits on every prekey + inbox route, with a WARN log on startup so operators see it. Single-tenant deployments only — multi-tenant relays must leave it unset. Documented in docs/DEPLOYMENT.md. Reported by Prism: ~6 pair attempts/hour from a single dev IP + the sidecar's register call tripped the 5/hour REGISTER_LIMIT every dev iteration. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
143 lines
6.3 KiB
Markdown
143 lines
6.3 KiB
Markdown
# 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
|
|
|
|
```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
|
|
```
|
|
|
|
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`](../examples/05-dokploy-deployment/docker-compose.yml)
|
|
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:
|
|
```bash
|
|
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`:
|
|
|
|
```yaml
|
|
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`](./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`](./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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```bash
|
|
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.
|