Sidecars

norsk-ctl launches each instance as a docker-compose project containing norsk-media and norsk-studio. Sidecars are an admin-only escape hatch that lets you merge additional services: into that project — companion containers (event subscribers, custom sources, glue services) that share the instance’s lifecycle.

Under the hood the sidecar is just a docker-compose file merged into the instance’s project, so it can also override values on existing services if you need to — but the primary use case (and the name) is companion containers.

Caution

This is a CLI-only admin feature. There is no UI surface for editing the sidecar file; it lives on disk under your working directory and you maintain it by hand.

When to use it

• You have a small auxiliary container that needs to talk to norsk-studio or norsk-media and come up/down with the instance.
• You want to depend on norsk-studio: condition: service_healthy so the sidecar only starts after Studio is responsive.
• The shape of the sidecar varies enough that hard-coding it into norsk-ctl would be a leaky abstraction.

If you’re spinning up a generic SRT/RTMP source pump, see norsk-ctl source instead — that’s the typed path.

How it works

1. Drop your sidecar file under <workingDirectory>/<somewhere>/<sidecar>.yaml.
2. Pass --sidecars <relative-path> (repeatable) on norsk-ctl instance launch. Paths are resolved relative to the working directory; absolute paths are rejected.
3. norsk-ctl validates each file exists and parses as YAML, then appends them to the docker compose -f chain after its own templates. Sidecar files merge last, so they can override service definitions if needed.
4. The sidecar paths are persisted with the launch config, so instance relaunch and workflow switches keep the sidecars.

Example: a Node sidecar that subscribes to Studio’s firehose

This mirrors a real integration — an LLM-backed reasoning processor in Studio emits events, and a small Node container POSTs them to an external HTTP endpoint.

<workingDirectory>/sidecars/connector.yaml:

services:
  connector:
    image: my-org/scte35-connector:1.0.0
    container_name: connector-${NORSK_CTL_INSTANCE_ID}
    networks: [norsk-net]
    depends_on:
      norsk-studio:
        condition: service_healthy
    environment:
      STUDIO_WS_URL: ws://norsk-studio-${NORSK_CTL_INSTANCE_ID}:8000/live/firehose
      DAZN_CHANNEL_ID: TX09
      DRY_RUN: "1"
    volumes:
      - ${WORKFLOWS_HOST_DIR}/secrets/dazn.json:/run/secrets/dazn.json:ro
    restart: unless-stopped

Launch:

norsk-ctl instance launch demo \
  --workflow my-flow.yaml \
  --sidecars sidecars/connector.yaml

After launch, norsk-ctl instance show demo lists the sidecar alongside the studio + media containers, and the UI’s instance detail page renders it.

Networking

Today every instance shares one global norsk-net bridge (the external: true network created on first launch). Reference it as networks: [norsk-net] in your sidecar. Container DNS within the project resolves the canonical names (norsk-studio-<id>, norsk-media-<id>).

Note

Per-instance networks are tracked as a future change; when they ship, the network name moves to norsk-net-<id> but the alias norsk-net inside the project remains stable for sidecars.

Logs

Use the existing logs endpoint with the sidecar’s container name:

norsk-ctl instance logs demo --container connector-demo

The web UI’s logs view targets media/studio only — sidecar logs are CLI-side for now.

Available environment variables

norsk-ctl exposes the same compose env vars to sidecar files as it uses internally. The most useful ones:

Var	What
NORSK_CTL_INSTANCE_ID	The instance id (<project> in compose terms)
WORKFLOWS_HOST_DIR	Host path mounted as /data in studio + media
LOGS_STUDIO_HOST_DIR	Per-instance studio log directory on host
STUDIO_INTERNAL_PORT	Port studio listens on inside its container

The full list lives in backend/src/docker/build-env.ts:buildEnv if you need an env var you don’t see here.

Caveats

• Naming. All instances share the global network and DNS namespace. Use ${NORSK_CTL_INSTANCE_ID} in your container_name to avoid collisions across instances.
• No schema enforcement. norsk-ctl only checks the file is valid YAML — docker compose config does the rest at launch time. If your sidecar references an unknown env var or has a typo, you’ll see compose’s error, not a norsk-ctl validation message.
• Image pulling. Pre-pull / rebuild your sidecar image before launch; norsk-ctl doesn’t preflight sidecar images the way it does for studio + media.
• Removed instances. norsk-ctl instance remove issues docker compose down against the project, which removes sidecars too — including any volumes declared without external references.
• Overrides, not just additions. Because the file is merged into the compose project, you can also override existing service config (env vars on studio/media, extra volumes). Use sparingly — that path bypasses norsk-ctl’s assumptions.