UDX Worker Guide

Use something simpler when

• A plain one-process container with normal env vars and stdout logs is enough.
• You need a job queue, scheduler product, service mesh, or deployment orchestrator.
• The only question is which tag to pull; use Docker Hub, repo docs, or checked-in manifests.

Other auth paths (docs)

Use these for CI/Kubernetes or when keyless local auth is not possible.

• GitHub Actions Workload Identity (keyless)
• Kubernetes workload identity / service account mapping
• JSON key file fallback (legacy, less secure)

When to build a child image

• Use udx-worker when the app can be mounted or copied by the deployment pipeline.
• Use udx-worker-nodejs or udx-worker-php when the language runtime should be part of the image contract.
• Build a specialized child image when startup scripts, service defaults, or system packages must ship together.
• Use public GitHub and Docker Hub search links to discover Worker-based repos/images; worker images --all is from the deprecated deployment CLI path.
• Do not put deployment orchestration in the child image; keep target selection, mounts, ports, and rollout policy in the host platform.

Extension patterns that hold up

Real child images tend to stay maintainable when they keep the Worker contract obvious and leave environment-specific choices to the deployment platform.

• Pin the parent Worker image in release paths instead of inheriting from a floating tag.
• Add only the system packages, language packages, and CLIs the workload actually needs.
• Copy services.yaml and optional worker.yaml only when they are part of the image contract.
• Put helper scripts, app libraries, and CLI wrappers in predictable paths with explicit permissions.
• Keep target env, credentials, mounts, ports, and rollout policy in Docker, Kubernetes, CI, or repo manifests.
• Switch back to the Worker runtime user before CMD unless the workload documents why it cannot.
• Validate with runtime output and in-container Worker commands before treating the image as releasable.

Minimal child image pattern

A child image should add workload dependencies and keep the Worker runtime contract intact.

FROM usabilitydynamics/udx-worker:0.41.0

COPY .config/worker/services.yaml /home/udx/.config/worker/services.yaml
COPY bin/ /home/udx/bin/

RUN chmod +x /home/udx/bin/*

Multi-stage app image pattern

Build assets in one stage, copy only runtime output into the Worker stage, then keep the same config/services contract.

FROM usabilitydynamics/udx-worker-nodejs:0.32.0 AS builder
WORKDIR /usr/src/app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM usabilitydynamics/udx-worker-nodejs:0.32.0 AS runtime
COPY --from=builder /usr/src/app/dist /usr/src/app/dist
COPY .config/worker/services.yaml /home/udx/.config/worker/services.yaml
USER udx
CMD ["/usr/local/bin/init.sh"]

Run a child image with mounted config

Pick the image, mount app code where that image expects it, and mount Worker runtime config read-only.

docker run --rm \
  -v "$PWD:/usr/src/app" \
  -v "$PWD/.config/worker:/home/udx/.config/worker:ro" \
  usabilitydynamics/udx-worker-nodejs:latest

Validate the image contract

Release checks should prove the image contains the expected runtime files and that Worker can apply them.

mkdir -p runtime-output

docker run --rm \
  -e WORKER_RUNTIME_OUTPUT=true \
  -v "$PWD/.config/worker:/home/udx/.config/worker:ro" \
  usabilitydynamics/udx-worker-nodejs:latest \
  true > runtime-output/runtime.json

jq -e '.paths.services_config | type == "string"' runtime-output/runtime.json