Deployment

Deploying Sp00ky requires running the Sp00ky Sidecar (SSP) alongside your SurrealDB instance. For production deployments, the Scheduler coordinates multiple SSP instances.

Architecture

SurrealDB: Your persistent data store.
Sp00ky SSP (Sidecar): A backend service that monitors SurrealDB for changes and maintains materialized views.
Scheduler (optional): Central coordinator for distributed deployments with multiple SSPs. Maintains a RocksDB snapshot replica and WAL.
Client: Connects directly to SurrealDB.

Single Node (Development)

The simplest setup for development and testing. No scheduler needed.

yaml

services:
  surrealdb:
    image: surrealdb/surrealdb:v3.1.0-beta.3
    command: start --user root --pass root rocksdb:/data/db
    ports:
      - "8666:8000"
    volumes:
      - ./data:/data

  ssp:
    image: ghcr.io/sp00ky-org/ssp-server:canary
    environment:
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_AUTH_SECRET=your-secret-token
      - SPKY_SSP_REF_MODE=dedicated
    ports:
      - "8667:8667"
    depends_on:
      - surrealdb

Distributed (Production)

For production with high availability and horizontal scaling, use a Scheduler with multiple SSP instances.

yaml

services:
  surrealdb:
    image: surrealdb/surrealdb:v3.1.0-beta.3
    command: start --user root --pass root rocksdb:/data/db
    ports:
      - "8666:8000"
    volumes:
      - surreal-data:/data

  scheduler:
    image: ghcr.io/sp00ky-org/scheduler:canary
    environment:
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_SCHEDULER_ID=scheduler-01
      - SPKY_AUTH_SECRET=your-secret-token
    # Bind host/port and storage paths come from the scheduler's
    # sp00ky.yml (ingest_host, ingest_port, replica_db_path, wal_path).
    ports:
      - "9667:9667"
    volumes:
      - scheduler-data:/app/data
    depends_on:
      - surrealdb

  ssp-1:
    image: ghcr.io/sp00ky-org/ssp-server:canary
    environment:
      - SPKY_SSP_ID=ssp-01
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_AUTH_SECRET=your-secret-token
      - SPKY_SCHEDULER_URL=http://scheduler:9667
      - SPKY_SSP_ADVERTISE_ADDR=ssp-1:8667
      - SPKY_SSP_REF_MODE=dedicated
      - HEARTBEAT_INTERVAL_MS=5000
    ports:
      - "8667:8667"
    depends_on:
      - surrealdb
      - scheduler

  ssp-2:
    image: ghcr.io/sp00ky-org/ssp-server:canary
    environment:
      - SPKY_SSP_ID=ssp-02
      - SPKY_DB_WS=ws://surrealdb:8000
      - SPKY_DB_USER=root
      - SPKY_DB_PASS=root
      - SPKY_DB_NS=main
      - SPKY_DB_NAME=app
      - SPKY_SSP_LISTEN_ADDR=0.0.0.0:8667
      - SPKY_AUTH_SECRET=your-secret-token
      - SPKY_SCHEDULER_URL=http://scheduler:9667
      - SPKY_SSP_ADVERTISE_ADDR=ssp-2:8667
      - SPKY_SSP_REF_MODE=dedicated
      - HEARTBEAT_INTERVAL_MS=5000
    ports:
      - "8668:8667"
    depends_on:
      - surrealdb
      - scheduler

volumes:
  surreal-data:
  scheduler-data:

Environment Variables

SSP (Sidecar)

All SPKY_* vars below are read directly from the process environment.

Variable	Description	Default
`SPKY_SSP_LISTEN_ADDR`	Address and port for the SSP HTTP server	`0.0.0.0:8667`
`SPKY_AUTH_SECRET`	Bearer token for authenticating SSP API requests. When unset the auth middleware accepts any bearer (dev only).	(empty)
`SPKY_DB_WS`	SurrealDB WebSocket URL	`ws://127.0.0.1:8000`
`SPKY_DB_USER`	SurrealDB username	`root`
`SPKY_DB_PASS`	SurrealDB password	`root`
`SPKY_DB_NS`	SurrealDB namespace	`test`
`SPKY_DB_NAME`	SurrealDB database	`test`
`SPKY_SCHEDULER_URL`	Scheduler URL (enables distributed mode)	(unset)
`SPKY_SSP_ID`	Unique SSP identifier	`ssp-<uuid>`
`SPKY_SSP_ADVERTISE_ADDR`	Externally reachable `host:port` for this SSP	(unset)
`HEARTBEAT_INTERVAL_MS`	Heartbeat interval in ms	`5000`
`TTL_CLEANUP_INTERVAL_SECS`	View TTL cleanup interval	`60`
`SPKY_SSP_REF_MODE`	`_00_list_ref` storage layout: `dedicated` (per-user tables; works around the SurrealDB v3 LIVE permission gap) or `single` (legacy shared table). Mirrors `refMode` in `sp00ky.yml`.	`dedicated`
`SPKY_SSP_QUERY_UPDATE_THROTTLE_MS`	Window (ms) over which the SSP coalesces query edge-update writes to `_00_list_ref` into one batched transaction, so a burst of view updates lands as a few batched `LIVE` deliveries instead of one transaction per record. `0` disables batching (flush each update immediately). See Architecture.	`100`
`SPKY_JOB_CONFIG`	JSON-encoded `{ "job_tables": { … } }` describing backends the SSP can dispatch to.	(unset)
`SPKY_CRDT_CACHE_SIZE`	In-memory CRDT cache capacity	`10000`
`SPKY_CRDT_FIELDS`	JSON override for `@crdt` field detection, e.g. `{"thread":["content"]}`	(auto)
`SPKY_SSP_BOOTSTRAP_PAGE_SIZE`	Rows pulled per `/proxy/query` page	`500`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry collector endpoint for SSP metrics	(unset)
`OTEL_SERVICE_NAME`	OTEL service identifier	`ssp`

Scheduler

The scheduler reads most of its config from sp00ky.yml. The SPKY_* env vars below override the corresponding YAML field — every other field (ingest_host, ingest_port, load_balance, heartbeat_*, bootstrap_*, replica_db_path, wal_path, ssp_poll_interval_ms, max_buffer_per_ssp, job_tables) is YAML only.

Variable	Description	Default
`SPKY_SCHEDULER_ID`	Unique scheduler identifier	`scheduler-<uuid>`
`SPKY_DB_WS`	SurrealDB WebSocket URL	`ws://localhost:8000`
`SPKY_DB_NS`	SurrealDB namespace	`sp00ky`
`SPKY_DB_NAME`	SurrealDB database	`sp00ky`
`SPKY_DB_USER`	SurrealDB username	`root`
`SPKY_DB_PASS`	SurrealDB password	`root`
`SPKY_SNAPSHOT_UPDATE_INTERVAL_SECS`	Snapshot update interval (seconds)	`300`
`SPKY_BOOTSTRAP_PAGE_SIZE`	Rows read per bootstrap page from the replica	`500`
`SPKY_AUTH_SECRET`	Optional shared secret; when set, callers to `/proxy/*` must send `Authorization: Bearer <secret>`.	(empty)
`SPKY_SCHEDULER_BACKENDS`	JSON-encoded backend list (job-runner configuration)	(unset)