Skip to content

Deployment ​

This guide covers the Nekostick/svchost path used by the SmartClass fleet: one compose document declares the five services (teamusers, filewarehouse, webcam-server, dispatchub, merge), the Host injects addresses, ports and secrets, and dispatchub is deployed as a singleton scheduler.

Prerequisites ​

  • PostgreSQL 16 or newer, reachable from the dispatchub launch. The service applies its embedded goose migrations on startup; no external migration tool is needed. Every object it creates lives in the schema smartclass_dispatchub, which it creates on the first migrate, so the DSN role needs no rights on the database's public schema. A role that does not own the database cannot create a schema: a DBA creates it once and grants it, and dispatchub then uses it as-is.
  • A teamusers instance with the nine dispatch:* keys registered and a service credential for dispatchub. See Permissions and access control.
  • A smartclass-webcam-server instance with its devices provisioned and an nsc-filehouse (or S3) media sink configured upstream. dispatchub stores only ids; it never touches the media.
  • A smartclass-merge instance with its own database, a writable work directory sized for the recordings and the recordings destination bucket present in filehouse. Leave DISPATCH_MERGE_URL empty to deploy dispatchub without it: completing a recording is then recorded here and never merged.
  • svchost or any other supervisor that can run a Linux binary with environment variables.

Release artifact ​

The release workflow publishes dispatchub_<version>_<platform>_<arch>.zip for linux, windows and macos, each on amd64 (x64) and arm64, with the entry binary at the ZIP root and nothing else - dispatchub on Linux and macOS, dispatchub.exe on Windows. That layout is the svchost contract: the asset name carries the service id, the platform and the architecture, and the entry binary must carry the exact service name.

To build the same artifact locally:

sh
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags '-s -w -X main.version=v0.1.0' -o dist/dispatchub ./cmd/dispatchub

Configuration ​

Every value comes from the environment. A .env file is loaded only when DISPATCH_ENV_FILE is set, and real environment variables always win over it:

precedence: environment > DISPATCH_ENV_FILE file > default

Configuration reference ​

VariableDefaultRequiredPurpose
DISPATCH_LISTEN_ADDR:8081NoHTTP listen address.
DISPATCH_DSN-run, migratePostgreSQL DSN; the pool sets application_name=smartclass-dispatchub and pins search_path to the smartclass_dispatchub schema (a DSN that sets search_path itself wins).
DISPATCH_TIMEZONEAsia/ShanghaiNoTimezone used to turn (date, period) into instants.
DISPATCH_TEAMUSERS_URL-run (unless DISPATCH_DEV=true), register-permissionsteamusers base URL; JWKS is discovered under it.
DISPATCH_TEAMUSERS_ISSUERteamusersNoExpected iss claim.
DISPATCH_TEAMUSERS_AUDteamusersNoExpected aud claim - set it to the fleet value (nekostick).
DISPATCH_TEAMUSERS_CLIENT_ID-run (unless DISPATCH_DEV=true)client-credentials credential id for outbound calls (webcam-server + permission lookups).
DISPATCH_TEAMUSERS_CLIENT_SECRET-run (unless DISPATCH_DEV=true)client-credentials secret. Treat as a secret.
DISPATCH_TEAMUSERS_TIMEOUT5sNoIAM HTTP timeout.
DISPATCH_WEBCAM_URL-run (unless DISPATCH_DEV=true)smartclass-webcam-server base URL, e.g. http://webcam:8080.
DISPATCH_WEBCAM_TIMEOUT10sNoOutbound HTTP timeout.
DISPATCH_MERGE_URL-Nosmartclass-merge base URL; empty disables merging: a completed recording is never submitted.
DISPATCH_MERGE_TIMEOUT10sNoOutbound HTTP timeout.
DISPATCH_MERGE_POLL_INTERVAL5sNoCadence of merge-job submission retries and job polls.
DISPATCH_MERGE_POLL_TTL2hNoWall-clock budget of one merge before it is marked failed.
DISPATCH_FILEHOUSE_URL-Nonsc-filehouse base URL, e.g. http://filewarehouse:8080; it mints the merged video's presigned download_url for the artifacts response. Empty (the default) means no download URL is minted - the artifacts response then omits download_url - and it is never a presence requirement.
DISPATCH_FILEHOUSE_TIMEOUT10sNoOutbound HTTP timeout for the filehouse presign calls.
DISPATCH_SCHED_TICK30sNoScheduler scan interval.
DISPATCH_PRESTART2mNoHow early a session's recording starts.
DISPATCH_POSTSTOP_GRACE0sNoDelay before stopping at ends_at.
DISPATCH_START_RETRY_MAX3NoStart attempts before a session is marked failed.
DISPATCH_MISS_GRACE10mNoPast starts_at + grace a planned session becomes missed.
DISPATCH_PHOTO_POLL_INTERVAL2sNoPhoto-id resolution poll interval.
DISPATCH_PHOTO_POLL_TTL15mNoGive up on a photo (status unresolved) after this.
DISPATCH_MAX_CONCURRENT_COMMANDS8NoOutbound command concurrency cap.
DISPATCH_MAX_IMPORT_ROWS5000NoCSV row cap per import.
DISPATCH_DEVfalseNoDev bypass: synthetic claims, teamusers disabled. Local development only.
DISPATCH_LOG_LEVELinfoNoslog level: debug, info, warn or error.
DISPATCH_ENV_FILE-NoPath to a .env-style file; loaded at startup only when set.
DISPATCH_TEAMUSERS_ADMIN_TOKEN-register-permissionsteamusers admin bearer token; the -token flag wins. A secret.

DISPATCH_*_TIMEOUT, DISPATCH_SCHED_TICK, DISPATCH_PRESTART, DISPATCH_POSTSTOP_GRACE, DISPATCH_MISS_GRACE, DISPATCH_PHOTO_POLL_INTERVAL, DISPATCH_PHOTO_POLL_TTL, DISPATCH_MERGE_POLL_INTERVAL and DISPATCH_MERGE_POLL_TTL accept Go duration syntax (300ms, 2m, 1h). Loading fails fast on an unparsable duration, an unknown timezone or an unknown log level, and each subcommand then enforces only the variables it uses - run every endpoint and credential above, migrate the DSN, register-permissions the teamusers URL and its admin token - so a bad compose edit surfaces at startup, not at the first lesson, and a one-off migrate or catalog registration is never blocked by the runtime endpoints. The binary embeds the IANA time zone database (time/tzdata), so DISPATCH_TIMEZONE resolves on a host that has no system tzdata - a Windows development box or a scratch container needs nothing extra.

Fleet deployment (svchost) ​

The document below is the complete svchost.compose.yaml for the fleet; the same file is committed at the repository root. Field semantics are defined in the svchost compose reference.

yaml
# svchost compose for the SmartClass dispatch fleet.
# Field semantics: https://github.com/crazy4chicken/nekostick-svchost/blob/main/docs/compose.md
#
# strictSources is intentionally omitted (it defaults to false): a single
# source.sha256 cannot cover every architecture at once, because the per-arch
# ZIP assets have different digests. Pin sha256 only for a single-architecture
# deployment, or set strictSources: true together with a matching digest.
serviceScope: global

services:
  teamusers:
    source:
      release: "github:crazy4chicken/nsc-teamusers@v0.2.1" # asset teamusers_<version>_<arch>.zip, entry binary `teamusers`
      # sha256: "..." # optional single-arch pin; otherwise svchost verifies against the GitHub asset digest
    args: ["run"]
    env:
      TEAMUSERS_CONNECTION_STRING: "${HOST:TEAMUSERS_CONNECTION_STRING}"
      TEAMUSERS_KEY_DIR: /var/lib/teamusers/keys # persistent and writable; never point it at artifacts/ or tmp/
      TEAMUSERS_NODE_ID: teamusers
      TEAMUSERS_TOKEN_AUDIENCE: nekostick # MUST equal DISPATCH_TEAMUSERS_AUD and WEBCAM_TEAMUSERS_AUD
      TEAMUSERS_LOG_LEVEL: info
      # The listen address comes from the Host launch values; override with
      # TEAMUSERS_LISTEN_ADDRESS / TEAMUSERS_LISTEN_PORT if this deployment needs fixed values.
    start: eager # authentication is on the fleet's critical path, start with the host
    restart: on-failure
    health:
      type: http
      path: /healthz
      timeout: 5s
    route:
      prefix: /iam
      strip: true # /iam/auth/login reaches the child process as /auth/login

  filewarehouse:
    source:
      release: "github:crazy4chicken/nsc-filewarehouse@v0.1.0" # module nsc-filehouse; entry binary `filewarehouse`
      # sha256: "..." # optional single-arch pin
    args: ["run"]
    env:
      FILEHOUSE_DSN: "${HOST:FILEHOUSE_DSN}"
      FILEHOUSE_ADDR: "${HOST}"
      FILEHOUSE_PORT: "${PORT}"
      FILEHOUSE_BLOB_DIR: /var/lib/filehouse/blobs # persistent and writable; the segments and photos live here
      FILEHOUSE_KEY_DIR: /var/lib/filehouse/keys
      FILEHOUSE_NODE_ID: filewarehouse
      FILEHOUSE_PUBLIC_BASE_URL: "https://files.example.com/files" # public origin, route prefix included
      FILEHOUSE_TEAMUSERS_BASE_URL: "http://${HOST@teamusers}:${PORT@teamusers}"
      FILEHOUSE_TEAMUSERS_ISSUER: teamusers
      FILEHOUSE_TEAMUSERS_AUDIENCE: nekostick
      FILEHOUSE_TEAMUSERS_CLIENT_ID: filehouse-svc
      FILEHOUSE_TEAMUSERS_CLIENT_SECRET: "${HOST:FILEHOUSE_TEAMUSERS_CLIENT_SECRET}"
    start: eager # applies migrations at startup, before the first upload
    restart: on-failure
    health:
      type: http
      path: /healthz
      timeout: 5s
    route:
      prefix: /files
      strip: true

  webcam-server:
    source:
      release: "github:crazy4chicken/smartclass-webcam-server@v0.2.0"
    env:
      WEBCAM_LISTEN_ADDR: "${HOST}:${PORT}" # the Host assigns the port for this launch
      WEBCAM_DB_URL: "${HOST:WEBCAM_DB_URL}"
      WEBCAM_TEAMUSERS_URL: "http://${HOST@teamusers}:${PORT@teamusers}"
      WEBCAM_TEAMUSERS_AUD: nekostick
      WEBCAM_TEAMUSERS_CLIENT_ID: webcam-server-svc
      WEBCAM_TEAMUSERS_CLIENT_SECRET: "${HOST:WEBCAM_TEAMUSERS_CLIENT_SECRET}"
      WEBCAM_FILEHOUSE_URL: "http://${HOST@filewarehouse}:${PORT@filewarehouse}" # internal address, no route prefix; the media sink — omit it and webcam-server falls back to S3, then to noop (nothing is stored)
      WEBCAM_FILEHOUSE_BUCKET: webcam-segments
      WEBCAM_WS_TICKET_TTL: 60s
    start: eager
    restart: on-failure
    health:
      type: http
      path: /readyz # also covers the Postgres connection
      timeout: 5s
    route:
      prefix: /webcam
      strip: true # see the device-plane note below before publishing this prefix

  dispatchub:
    source:
      release: "github:crazy4chicken/smartclass-dispatchub@v0.1.0"
      # Before the first release exists, bootstrap from a local binary instead:
      # path: /opt/dispatchub/dispatchub
    env:
      DISPATCH_LISTEN_ADDR: "${HOST}:${PORT}"
      DISPATCH_DSN: "${HOST:DISPATCH_DSN}"
      DISPATCH_TIMEZONE: Asia/Shanghai
      DISPATCH_TEAMUSERS_URL: "http://${HOST@teamusers}:${PORT@teamusers}"
      DISPATCH_TEAMUSERS_ISSUER: teamusers
      DISPATCH_TEAMUSERS_AUD: nekostick
      DISPATCH_TEAMUSERS_CLIENT_ID: dispatchub-svc
      DISPATCH_TEAMUSERS_CLIENT_SECRET: "${HOST:DISPATCH_TEAMUSERS_CLIENT_SECRET}"
      DISPATCH_WEBCAM_URL: "http://${HOST@webcam-server}:${PORT@webcam-server}" # same-namespace service reference
      DISPATCH_MERGE_URL: "http://${HOST@merge}:${PORT@merge}" # same-namespace service reference; empty disables merging
      DISPATCH_FILEHOUSE_URL: "http://${HOST@filewarehouse}:${PORT@filewarehouse}" # same-namespace service reference; internal address, no route prefix; mints the merged video's presigned download_url
      DISPATCH_PRESTART: 2m
      DISPATCH_POSTSTOP_GRACE: 15s
      DISPATCH_LOG_LEVEL: info
    start: eager # the scheduler must be up before the first lesson window
    restart: on-failure # fatal errors exit non-zero; use `always` if a clean exit should also be restarted
    health:
      type: http
      path: /healthz
      timeout: 5s
    route:
      prefix: /dispatch
      strip: true # /dispatch/api/v1/... reaches the child process as /api/v1/...

  merge:
    source:
      release: "github:crazy4chicken/smartclass-merge@v0.1.0"
      # Before the first release exists, bootstrap from a local binary instead:
      # path: /opt/merge/merge
    args: ["run"]
    env:
      MERGE_LISTEN_ADDR: "${HOST}:${PORT}"
      MERGE_DSN: "${HOST:MERGE_DSN}"
      MERGE_TEAMUSERS_URL: "http://${HOST@teamusers}:${PORT@teamusers}"
      MERGE_TEAMUSERS_ISSUER: teamusers
      MERGE_TEAMUSERS_AUD: nekostick # MUST equal TEAMUSERS_TOKEN_AUDIENCE
      MERGE_TEAMUSERS_CLIENT_ID: merge-svc
      MERGE_TEAMUSERS_CLIENT_SECRET: "${HOST:MERGE_TEAMUSERS_CLIENT_SECRET}"
      MERGE_FILEHOUSE_URL: "http://${HOST@filewarehouse}:${PORT@filewarehouse}" # internal address, no route prefix
      MERGE_SOURCE_BUCKET: webcam-segments
      MERGE_DEST_BUCKET: recordings # must exist in filewarehouse; the merged video is written here
      MERGE_WORK_DIR: /var/lib/merge/work # persistent and writable; holds each job's temp video, size it for one recording per concurrent job
      MERGE_MAX_CONCURRENT_JOBS: "1" # one merge at a time; raise it only with CPU and disk headroom
      MERGE_LOG_LEVEL: info
      # MERGE_FFMPEG_PATH: /usr/bin/ffmpeg # uncomment to use a host ffmpeg instead of the embedded build
    start: eager # the queue should drain as soon as a recording stops producing segments
    restart: on-failure # fatal errors exit non-zero; use `always` if a clean exit should also be restarted
    health:
      type: http
      path: /readyz # covers Postgres, the work dir and the ffmpeg extraction; the first probe extracts the payload
      timeout: 15s
    route:
      prefix: /merge
      strip: true # /merge/api/v1/... reaches the child process as /api/v1/...

Before applying it to a real host, replace the two example values: the filehouse public origin (https://files.example.com/files) and the release versions if you pin a different one - the merge release tag in particular, because it carries the ffmpeg payload for that platform.

Template walkthrough ​

svchost resolves three template forms inside env values:

TemplateMeaning
${HOST:NAME}A host value stored on the svchost Host: every secret and every DSN is passed through this form. Nothing is stored in the compose file.
${HOST} / ${PORT}The address and port the Host leased to this launch. WEBCAM_LISTEN_ADDR and DISPATCH_LISTEN_ADDR bind to them.
${HOST@service} / ${PORT@service}The address and port assigned to another service in the same namespace, e.g. http://${HOST@teamusers}:${PORT@teamusers}. This is why no static port appears anywhere in the fleet.

Notes ​

  • No secret ever lives in the YAML. Every credential is a ${HOST:...} passthrough and every DSN comes from the host environment, so the file is committed as-is and the values stay in the Host.
  • Cross-service wiring uses launch templates. ${HOST@teamusers}:${PORT@teamusers} reads the referenced service's Host-assigned address, so no static port appears anywhere in the fleet; the target must be declared in the same global namespace (it is, above).
  • The service name is the release contract. services.<name> is the serviceId, so the release workflow must publish dispatchub_<version>_<platform>_<arch>.zip for linux, windows and macos (the 4-segment form - the platform segment is mandatory, and the legacy 3-segment name is matched on Linux hosts only) with the entry binary named exactly dispatchub - dispatchub.exe on Windows - at the ZIP root, and the process CWD will be the service root rather than that extraction directory.
  • A dangling ${...@svc} reference fails that service's sync. Dropping the filewarehouse block means also dropping WEBCAM_FILEHOUSE_URL, MERGE_FILEHOUSE_URL and DISPATCH_FILEHOUSE_URL; dropping merge means also dropping DISPATCH_MERGE_URL. An unresolvable service-name target is a sync failure, not a silent empty string. (The nsc-filewarehouse compose circulating in the fleet sets FILEWAREHOUSE_* names that do not match the binary's FILEHOUSE_* config constants - use the names above.)
  • Health paths differ in meaning. /healthz is the liveness check the supervisor should use; /readyz additionally probes Postgres and webcam-server here, and Postgres, the work dir and the ffmpeg extraction in the merge launch, so it belongs on the operator dashboard.
  • Device-plane exposure is an explicit decision. route.prefix: /webcam publishes the entire webcam-server surface, including the wdt_-token device plane (/ws/register, /ws/device/{ticket}). If devices must not be reachable through the host router, give webcam-server its own Host/compose without a route block and keep only dispatchub behind the gateway - dispatchub reaches it over the internal ${HOST@webcam-server} address either way.
  • One digest, one architecture. source.sha256 holds a single value, so it cannot match both the x64 and arm64 ZIPs; pin it for single-architecture deployments, or set strictSources: true together with the matching digest. Each merge asset also embeds a different ffmpeg payload, so its digest differs per architecture by construction.
  • The merge queue is shared through PostgreSQL, not the network. Every merge process watches the same merge_jobs table and claims with FOR UPDATE SKIP LOCKED, so a second merge replica does not double work - but it needs its own MERGE_WORK_DIR.
  • Scope choice. serviceScope: global (used above) shares one service root and one service-name namespace across configs - a duplicate service name makes the whole reconciliation round fail - while serviceScope: document isolates roots per config name. dispatchub must be declared exactly once in the global namespace, and it is a singleton scheduler: extra replicas idle on the advisory lock, they do not split work.

Field notes ​

teamusers

FieldNote
source.releasev0.2.1 publishes teamusers_<version>_<arch>.zip with the teamusers binary at the ZIP root.
source.sha256Optional; pin only for one architecture (see the digest note above).
args["run"] - the same subcommand the release artifact expects.
TEAMUSERS_CONNECTION_STRINGThe teamusers database DSN, from the Host.
TEAMUSERS_KEY_DIRPersistent and writable; holds the Ed25519 signing keys. Never point it at artifacts/ or tmp/.
TEAMUSERS_TOKEN_AUDIENCEMust equal DISPATCH_TEAMUSERS_AUD and WEBCAM_TEAMUSERS_AUD.
start / restarteager / on-failure: authentication is on the fleet's critical path.
healthGET /healthz is the supervisor's liveness probe.
routeprefix: /iam, strip: true: /iam/auth/login reaches the child as /auth/login.

filewarehouse

FieldNote
source.releaseThe module is nsc-filehouse; the asset ships the filewarehouse binary.
args["run"] - applies migrations at startup, before the first upload.
FILEHOUSE_DSNThe filehouse database DSN, from the Host.
FILEHOUSE_ADDR / FILEHOUSE_PORTBound to the launch's ${HOST}/${PORT} lease.
FILEHOUSE_BLOB_DIRPersistent and writable; segments and photos live here.
FILEHOUSE_KEY_DIRPersistent; filehouse signing/encryption keys.
FILEHOUSE_PUBLIC_BASE_URLThe public origin including the route prefix; replace the example host.
FILEHOUSE_TEAMUSERS_*Inbound token verification and the service credential; audience nekostick.
healthGET /healthz.
routeprefix: /files, strip: true.

webcam-server

FieldNote
source.releasePushing a v* tag publishes smartclass-webcam-server_<version>_<arch>.zip.
WEBCAM_LISTEN_ADDR${HOST}:${PORT} - the Host assigns the port for this launch.
WEBCAM_DB_URLwebcam-server's own database DSN, from the Host.
WEBCAM_TEAMUSERS_URLInternal address of the teamusers launch; no route prefix.
WEBCAM_TEAMUSERS_AUDMust equal the issuer's TEAMUSERS_TOKEN_AUDIENCE.
WEBCAM_TEAMUSERS_CLIENT_ID / ..._SECRETwebcam-server's service credential (also used for filehouse).
WEBCAM_FILEHOUSE_URLThe media sink over the internal address. Omit it and webcam-server falls back to S3, then to a no-op backend that stores nothing.
WEBCAM_FILEHOUSE_BUCKETBucket for segments; it must exist.
WEBCAM_WS_TICKET_TTLLifetime of the device registration ticket.
healthGET /readyz also covers the Postgres connection.
routeprefix: /webcam, strip: true; read the device-plane note above before publishing it.

dispatchub

FieldNote
source.releasedispatchub_<version>_linux_<arch>.zip, binary dispatchub; the commented path: is the bootstrap route before the first release exists.
DISPATCH_LISTEN_ADDR${HOST}:${PORT} - bind to the launch lease.
DISPATCH_DSNThe dispatchub database DSN; migrations are applied from the embedded FS at startup.
DISPATCH_TIMEZONEKeep Asia/Shanghai unless the school's wall clock says otherwise; a wrong value schedules the whole term wrongly.
DISPATCH_TEAMUSERS_URLInternal teamusers address; JWKS is discovered under it.
DISPATCH_TEAMUSERS_ISSUER / ..._AUDteamusers / nekostick; the audience must match TEAMUSERS_TOKEN_AUDIENCE.
DISPATCH_TEAMUSERS_CLIENT_ID / ..._SECRETdispatchub's service credential; the secret comes from the Host.
DISPATCH_WEBCAM_URLSame-namespace service reference to webcam-server.
DISPATCH_MERGE_URLSame-namespace service reference to the merge block below. Clear it and dispatchub stops creating merge jobs; a completed recording then keeps its segments only.
DISPATCH_FILEHOUSE_URLSame-namespace service reference to the filewarehouse block above, over the internal address with no route prefix. It is the only use dispatchub makes of filehouse: minting the merged video's presigned download_url per artifacts response. Clear it and the artifacts response omits download_url (the storage coordinates stay in dispatchub's database); the merge itself is unaffected.
DISPATCH_PRESTART / DISPATCH_POSTSTOP_GRACEExample overrides (2m / 15s); both default differently, see the reference table.
DISPATCH_LOG_LEVELslog JSON level.
start / restarteager (the scheduler must be up before the first lesson window) / on-failure (fatal errors exit non-zero; use always to also restart clean exits).
healthGET /healthz for the supervisor. Use /readyz on the dashboard: it also probes Postgres and webcam-server.
routeprefix: /dispatch, strip: true: /dispatch/api/v1/... reaches the child as /api/v1/....

merge

FieldNote
source.releasemerge_<version>_<platform>_<arch>.zip, binary merge; the commented path: is the bootstrap route before the first release exists. Each asset embeds the ffmpeg payload for its platform, so pin the tag that matches the host architecture.
MERGE_LISTEN_ADDR${HOST}:${PORT} - bind to the launch lease.
MERGE_DSNThe merge database DSN; migrations are applied from the embedded FS at startup.
MERGE_TEAMUSERS_URLInternal teamusers address; JWKS is discovered under it.
MERGE_TEAMUSERS_ISSUER / ..._AUDteamusers / nekostick; the audience must match TEAMUSERS_TOKEN_AUDIENCE.
MERGE_TEAMUSERS_CLIENT_ID / ..._SECRETmerge's service credential; the secret comes from the Host. It is also the token merge presents to filehouse, so filehouse must accept this teamusers issuer.
MERGE_FILEHOUSE_URLSame-namespace service reference to filewarehouse; both buckets must exist there.
MERGE_SOURCE_BUCKET / MERGE_DEST_BUCKETRead segments from the first (webcam-server's sink) and write merged videos to the second. dispatchub never sends a bucket: MERGE_SOURCE_BUCKET is the single source of truth and the destination defaults to MERGE_DEST_BUCKET.
MERGE_WORK_DIRPersistent and writable, sized for one recording per concurrent job. Never point it at artifacts/ or tmp/.
MERGE_MAX_CONCURRENT_JOBS1 unless the host has CPU and disk headroom.
MERGE_FFMPEG_PATHCommented out: the embedded build is the default. A host ffmpeg is the escape hatch when shipping a GPL binary is not acceptable.
start / restarteager (the queue should drain as soon as a recording stops producing segments) / on-failure (fatal errors exit non-zero; use always to also restart clean exits).
healthGET /readyz with a 15 s timeout, because the first probe extracts the embedded ffmpeg payload into MERGE_WORK_DIR.
routeprefix: /merge, strip: true: /merge/api/v1/... reaches the child as /api/v1/....

First-time setup ​

  1. Store the host values referenced by the compose file: TEAMUSERS_CONNECTION_STRING, FILEHOUSE_DSN, WEBCAM_DB_URL, DISPATCH_DSN, MERGE_DSN, and the service-client secrets used above (FILEHOUSE_TEAMUSERS_CLIENT_SECRET, WEBCAM_TEAMUSERS_CLIENT_SECRET, DISPATCH_TEAMUSERS_CLIENT_SECRET, MERGE_TEAMUSERS_CLIENT_SECRET).
  2. Register the nine dispatch:* keys in teamusers and bind them to roles. Either run dispatchub register-permissions against the instance or use the raw registration calls in the permissions guide.
  3. Register the six merge:* keys in teamusers and bind them to roles: merge:read:any, merge:read:team, merge:read:own, merge:write:any, merge:write:team and merge:write:own. merge register-permissions -token <teamusers admin token> upserts them idempotently against the instance, exactly as dispatchub register-permissions does for the dispatch:* catalog.
  4. Create the destination bucket the merged videos land in: recordings in the filehouse webcam-server already writes segments to. The source bucket (webcam-segments) must exist as well - it is webcam-server's sink - and a missing destination bucket makes merge reject every create with 400 invalid_request. Create both through the filehouse API or its console before the first job.
  5. Create the service credentials (filehouse-svc, webcam-server-svc, dispatchub-svc, merge-svc) in teamusers and place their secrets in the Host values.
  6. Give the dispatchub credential the cam:* keys it needs to call webcam-server: in practice cam:read:any and cam:control:any cover the union of the scope ladders dispatchub uses.
  7. Give the dispatchub credential the two merge:* keys it needs to drive the merge queue: merge:write:any to create a job per completed recording and merge:read:any to poll it, in addition to the cam:* keys. Without them merge answers 403 insufficient_permissions and the merge row stays on its submission attempts until the TTL marks it failed - the recording itself is unaffected.
  8. Give the dispatchub credential the two filehouse keys it needs to mint the merged video's download URL on the destination bucket (recordings): filehouse:share:any and filehouse:read:any. Both are required, because minting a presigned GET evaluates two separate grants against the bucket resource: filehouse:share:any authorizes minting the URL, and filehouse:read:any authorizes the read the URL will exercise when it is redeemed. Missing either one makes POST /api/v1/presign answer 403; the artifacts response then omits download_url and the caller cannot fetch the merged video. Scope the grants to the bucket if the filehouse policy supports it - dispatchub needs them only on the merge destination.
  9. Give the merge credential its filehouse access: merge lists the source bucket and writes the destination bucket with the merge-svc token, so filehouse's policy for that account must allow reads on webcam-segments and writes on recordings. merge needs no merge:* key of its own - those exist for its callers.
  10. Bind at least one room (PUT /api/v1/rooms/{room_code}) before the first import, otherwise every CSV row fails validation with room_not_bound.
  11. Apply the compose document and verify: GET /dispatch/readyz answers 200 through the host route, dispatchub status prints the redacted configuration with a reachable database, webcam-server, merge and filehouse (the filehouse probe appears only when DISPATCH_FILEHOUSE_URL is set), and GET /merge/readyz answers 200 for the merge launch itself.

Health and diagnostics ​

ProbeMeaning
GET /healthzLiveness: 200 while the process lives. This is the supervisor's probe.
GET /readyzReadiness: Postgres ping plus GET {DISPATCH_WEBCAM_URL}/readyz. Use it on the operator dashboard.
dispatchub statusPrints the redacted configuration, the database version and webcam-server reachability, then exits. Also probes merge (GET {DISPATCH_MERGE_URL}/readyz) when DISPATCH_MERGE_URL is set, and filehouse (GET {DISPATCH_FILEHOUSE_URL}/readyz, a public route) when DISPATCH_FILEHOUSE_URL is set.
dispatchub doctorRuns the same checks with a 30 s timeout and exits non-zero on failure. Suitable for a cron or a deployment gate.

Security notes:

  • DISPATCH_DSN and DISPATCH_TEAMUSERS_CLIENT_SECRET are secrets. Never commit them, paste them into an issue, or print them; status replaces secret values with <redacted>.
  • DISPATCH_DEV=true disables teamusers entirely. Never set it on a host that is reachable from a network you do not control.