Appearance
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'spublicschema. 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
recordingsdestination bucket present in filehouse. LeaveDISPATCH_MERGE_URLempty 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/dispatchubConfiguration
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_FILEfile > default
Configuration reference
| Variable | Default | Required | Purpose |
|---|---|---|---|
DISPATCH_LISTEN_ADDR | :8081 | No | HTTP listen address. |
DISPATCH_DSN | - | run, migrate | PostgreSQL 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_TIMEZONE | Asia/Shanghai | No | Timezone used to turn (date, period) into instants. |
DISPATCH_TEAMUSERS_URL | - | run (unless DISPATCH_DEV=true), register-permissions | teamusers base URL; JWKS is discovered under it. |
DISPATCH_TEAMUSERS_ISSUER | teamusers | No | Expected iss claim. |
DISPATCH_TEAMUSERS_AUD | teamusers | No | Expected 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_TIMEOUT | 5s | No | IAM HTTP timeout. |
DISPATCH_WEBCAM_URL | - | run (unless DISPATCH_DEV=true) | smartclass-webcam-server base URL, e.g. http://webcam:8080. |
DISPATCH_WEBCAM_TIMEOUT | 10s | No | Outbound HTTP timeout. |
DISPATCH_MERGE_URL | - | No | smartclass-merge base URL; empty disables merging: a completed recording is never submitted. |
DISPATCH_MERGE_TIMEOUT | 10s | No | Outbound HTTP timeout. |
DISPATCH_MERGE_POLL_INTERVAL | 5s | No | Cadence of merge-job submission retries and job polls. |
DISPATCH_MERGE_POLL_TTL | 2h | No | Wall-clock budget of one merge before it is marked failed. |
DISPATCH_FILEHOUSE_URL | - | No | nsc-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_TIMEOUT | 10s | No | Outbound HTTP timeout for the filehouse presign calls. |
DISPATCH_SCHED_TICK | 30s | No | Scheduler scan interval. |
DISPATCH_PRESTART | 2m | No | How early a session's recording starts. |
DISPATCH_POSTSTOP_GRACE | 0s | No | Delay before stopping at ends_at. |
DISPATCH_START_RETRY_MAX | 3 | No | Start attempts before a session is marked failed. |
DISPATCH_MISS_GRACE | 10m | No | Past starts_at + grace a planned session becomes missed. |
DISPATCH_PHOTO_POLL_INTERVAL | 2s | No | Photo-id resolution poll interval. |
DISPATCH_PHOTO_POLL_TTL | 15m | No | Give up on a photo (status unresolved) after this. |
DISPATCH_MAX_CONCURRENT_COMMANDS | 8 | No | Outbound command concurrency cap. |
DISPATCH_MAX_IMPORT_ROWS | 5000 | No | CSV row cap per import. |
DISPATCH_DEV | false | No | Dev bypass: synthetic claims, teamusers disabled. Local development only. |
DISPATCH_LOG_LEVEL | info | No | slog level: debug, info, warn or error. |
DISPATCH_ENV_FILE | - | No | Path to a .env-style file; loaded at startup only when set. |
DISPATCH_TEAMUSERS_ADMIN_TOKEN | - | register-permissions | teamusers 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:
| Template | Meaning |
|---|---|
${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 theserviceId, so the release workflow must publishdispatchub_<version>_<platform>_<arch>.zipforlinux,windowsandmacos(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 exactlydispatchub-dispatchub.exeon 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 thefilewarehouseblock means also droppingWEBCAM_FILEHOUSE_URL,MERGE_FILEHOUSE_URLandDISPATCH_FILEHOUSE_URL; droppingmergemeans also droppingDISPATCH_MERGE_URL. An unresolvable service-name target is a sync failure, not a silent empty string. (Thensc-filewarehousecompose circulating in the fleet setsFILEWAREHOUSE_*names that do not match the binary'sFILEHOUSE_*config constants - use the names above.) - Health paths differ in meaning.
/healthzis the liveness check the supervisor should use;/readyzadditionally probes Postgres and webcam-server here, and Postgres, the work dir and the ffmpeg extraction in themergelaunch, so it belongs on the operator dashboard. - Device-plane exposure is an explicit decision.
route.prefix: /webcampublishes the entire webcam-server surface, including thewdt_-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 arouteblock and keep only dispatchub behind the gateway - dispatchub reaches it over the internal${HOST@webcam-server}address either way. - One digest, one architecture.
source.sha256holds a single value, so it cannot match both the x64 and arm64 ZIPs; pin it for single-architecture deployments, or setstrictSources: truetogether 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_jobstable and claims withFOR UPDATE SKIP LOCKED, so a secondmergereplica does not double work - but it needs its ownMERGE_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 - whileserviceScope: documentisolates 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
| Field | Note |
|---|---|
source.release | v0.2.1 publishes teamusers_<version>_<arch>.zip with the teamusers binary at the ZIP root. |
source.sha256 | Optional; pin only for one architecture (see the digest note above). |
args | ["run"] - the same subcommand the release artifact expects. |
TEAMUSERS_CONNECTION_STRING | The teamusers database DSN, from the Host. |
TEAMUSERS_KEY_DIR | Persistent and writable; holds the Ed25519 signing keys. Never point it at artifacts/ or tmp/. |
TEAMUSERS_TOKEN_AUDIENCE | Must equal DISPATCH_TEAMUSERS_AUD and WEBCAM_TEAMUSERS_AUD. |
start / restart | eager / on-failure: authentication is on the fleet's critical path. |
health | GET /healthz is the supervisor's liveness probe. |
route | prefix: /iam, strip: true: /iam/auth/login reaches the child as /auth/login. |
filewarehouse
| Field | Note |
|---|---|
source.release | The module is nsc-filehouse; the asset ships the filewarehouse binary. |
args | ["run"] - applies migrations at startup, before the first upload. |
FILEHOUSE_DSN | The filehouse database DSN, from the Host. |
FILEHOUSE_ADDR / FILEHOUSE_PORT | Bound to the launch's ${HOST}/${PORT} lease. |
FILEHOUSE_BLOB_DIR | Persistent and writable; segments and photos live here. |
FILEHOUSE_KEY_DIR | Persistent; filehouse signing/encryption keys. |
FILEHOUSE_PUBLIC_BASE_URL | The public origin including the route prefix; replace the example host. |
FILEHOUSE_TEAMUSERS_* | Inbound token verification and the service credential; audience nekostick. |
health | GET /healthz. |
route | prefix: /files, strip: true. |
webcam-server
| Field | Note |
|---|---|
source.release | Pushing 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_URL | webcam-server's own database DSN, from the Host. |
WEBCAM_TEAMUSERS_URL | Internal address of the teamusers launch; no route prefix. |
WEBCAM_TEAMUSERS_AUD | Must equal the issuer's TEAMUSERS_TOKEN_AUDIENCE. |
WEBCAM_TEAMUSERS_CLIENT_ID / ..._SECRET | webcam-server's service credential (also used for filehouse). |
WEBCAM_FILEHOUSE_URL | The 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_BUCKET | Bucket for segments; it must exist. |
WEBCAM_WS_TICKET_TTL | Lifetime of the device registration ticket. |
health | GET /readyz also covers the Postgres connection. |
route | prefix: /webcam, strip: true; read the device-plane note above before publishing it. |
dispatchub
| Field | Note |
|---|---|
source.release | dispatchub_<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_DSN | The dispatchub database DSN; migrations are applied from the embedded FS at startup. |
DISPATCH_TIMEZONE | Keep Asia/Shanghai unless the school's wall clock says otherwise; a wrong value schedules the whole term wrongly. |
DISPATCH_TEAMUSERS_URL | Internal teamusers address; JWKS is discovered under it. |
DISPATCH_TEAMUSERS_ISSUER / ..._AUD | teamusers / nekostick; the audience must match TEAMUSERS_TOKEN_AUDIENCE. |
DISPATCH_TEAMUSERS_CLIENT_ID / ..._SECRET | dispatchub's service credential; the secret comes from the Host. |
DISPATCH_WEBCAM_URL | Same-namespace service reference to webcam-server. |
DISPATCH_MERGE_URL | Same-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_URL | Same-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_GRACE | Example overrides (2m / 15s); both default differently, see the reference table. |
DISPATCH_LOG_LEVEL | slog JSON level. |
start / restart | eager (the scheduler must be up before the first lesson window) / on-failure (fatal errors exit non-zero; use always to also restart clean exits). |
health | GET /healthz for the supervisor. Use /readyz on the dashboard: it also probes Postgres and webcam-server. |
route | prefix: /dispatch, strip: true: /dispatch/api/v1/... reaches the child as /api/v1/.... |
merge
| Field | Note |
|---|---|
source.release | merge_<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_DSN | The merge database DSN; migrations are applied from the embedded FS at startup. |
MERGE_TEAMUSERS_URL | Internal teamusers address; JWKS is discovered under it. |
MERGE_TEAMUSERS_ISSUER / ..._AUD | teamusers / nekostick; the audience must match TEAMUSERS_TOKEN_AUDIENCE. |
MERGE_TEAMUSERS_CLIENT_ID / ..._SECRET | merge'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_URL | Same-namespace service reference to filewarehouse; both buckets must exist there. |
MERGE_SOURCE_BUCKET / MERGE_DEST_BUCKET | Read 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_DIR | Persistent and writable, sized for one recording per concurrent job. Never point it at artifacts/ or tmp/. |
MERGE_MAX_CONCURRENT_JOBS | 1 unless the host has CPU and disk headroom. |
MERGE_FFMPEG_PATH | Commented out: the embedded build is the default. A host ffmpeg is the escape hatch when shipping a GPL binary is not acceptable. |
start / restart | eager (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). |
health | GET /readyz with a 15 s timeout, because the first probe extracts the embedded ffmpeg payload into MERGE_WORK_DIR. |
route | prefix: /merge, strip: true: /merge/api/v1/... reaches the child as /api/v1/.... |
First-time setup
- 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). - Register the nine
dispatch:*keys in teamusers and bind them to roles. Either rundispatchub register-permissionsagainst the instance or use the raw registration calls in the permissions guide. - 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:teamandmerge:write:own.merge register-permissions -token <teamusers admin token>upserts them idempotently against the instance, exactly asdispatchub register-permissionsdoes for thedispatch:*catalog. - Create the destination bucket the merged videos land in:
recordingsin 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 with400 invalid_request. Create both through the filehouse API or its console before the first job. - Create the service credentials (
filehouse-svc,webcam-server-svc,dispatchub-svc,merge-svc) in teamusers and place their secrets in the Host values. - Give the dispatchub credential the
cam:*keys it needs to call webcam-server: in practicecam:read:anyandcam:control:anycover the union of the scope ladders dispatchub uses. - Give the dispatchub credential the two
merge:*keys it needs to drive the merge queue:merge:write:anyto create a job per completed recording andmerge:read:anyto poll it, in addition to thecam:*keys. Without them merge answers403 insufficient_permissionsand the merge row stays on its submission attempts until the TTL marks it failed - the recording itself is unaffected. - 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:anyandfilehouse:read:any. Both are required, because minting a presigned GET evaluates two separate grants against the bucket resource:filehouse:share:anyauthorizes minting the URL, andfilehouse:read:anyauthorizes the read the URL will exercise when it is redeemed. Missing either one makesPOST /api/v1/presignanswer403; the artifacts response then omitsdownload_urland 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. - Give the merge credential its filehouse access: merge lists the source bucket and writes the destination bucket with the
merge-svctoken, so filehouse's policy for that account must allow reads onwebcam-segmentsand writes onrecordings. merge needs nomerge:*key of its own - those exist for its callers. - Bind at least one room (
PUT /api/v1/rooms/{room_code}) before the first import, otherwise every CSV row fails validation withroom_not_bound. - Apply the compose document and verify:
GET /dispatch/readyzanswers 200 through the host route,dispatchub statusprints the redacted configuration with a reachable database, webcam-server, merge and filehouse (the filehouse probe appears only whenDISPATCH_FILEHOUSE_URLis set), andGET /merge/readyzanswers 200 for the merge launch itself.
Health and diagnostics
| Probe | Meaning |
|---|---|
GET /healthz | Liveness: 200 while the process lives. This is the supervisor's probe. |
GET /readyz | Readiness: Postgres ping plus GET {DISPATCH_WEBCAM_URL}/readyz. Use it on the operator dashboard. |
dispatchub status | Prints 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 doctor | Runs 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_DSNandDISPATCH_TEAMUSERS_CLIENT_SECRETare secrets. Never commit them, paste them into an issue, or print them;statusreplaces secret values with<redacted>.DISPATCH_DEV=truedisables teamusers entirely. Never set it on a host that is reachable from a network you do not control.