UDX Worker Logo

UDX Worker Guide

Operational reference for UDX Worker base and child images.

Section-level docs are linked where each topic is used.

Worker Docs CLI Deploy Docs Base Repo Docker Hub

Quick Start

Fastest path is @udx/worker-deployment. One action per command, copy and run.

Step 1. Install CLI

Install once on your machine.

npm install -g @udx/worker-deployment

Step 2. Generate deploy.yml

Create template in current directory, then edit image and mounts.

worker config

Step 3. Preview run command

Safe check before starting container.

worker run --dry-run

Step 4. Run

Execute deployment from your updated deploy.yml.

worker run
CLI Deploy Guide worker-deployment Repo Worker Docs Index

Validate Loop

Fast host-to-container checks before CI.

Step 1. On localhost (host machine)

Preview generated run command

worker run --dry-run

Launch container

worker run

Step 2. Inside container shell

Inspect services

worker service list

Stream service logs

worker service logs firebase --tail 100 --follow
CLI Runtime Commands Deploy CLI Commands

Runtime Model

Keep runtime and deployment concerns separate.

Concern File Purpose
Runtime env + secrets worker.yaml Defines env values and secret references inside container
Runtime process orchestration services.yaml Defines supervised services and commands
Deployment contract deploy.yml Chooses image, mounts, ports, command/args outside container

Common pitfall: editing runtime files when you actually need to change deployment behavior.

Runtime Config Docs Deploy Docs

Runtime Config

Keep worker.yaml for runtime defaults only.

  • config.env sets default runtime values.
  • config.secrets uses provider refs like gcp/<project>/<secret>.
  • Deployment env vars override worker.yaml (for all deployment types).
# /home/udx/.config/worker/worker.yaml
kind: workerConfig
version: udx.io/worker-v1/config
config:
  env:
    LOG_LEVEL: "info"
  secrets:
    DB_PASSWORD: "aws/db-password/us-west-2"
    API_KEY: "azure/kv-prod/api-key"
    SERVICE_TOKEN: "gcp/my-project/service-token"
Runtime Config Reference

Runtime Services

Define supervised services and their command startup contract. 

# /home/udx/.config/worker/services.yaml
kind: workerService
version: udx.io/worker-v1/service
services:
  - name: "api"
    command: "bash -lc 'exec /home/udx/bin/start-api.sh'"
    autostart: true
    autorestart: true
    envs:
      - "PORT=8080"
      - "SERVICE_NAME=api"

  - name: "scheduler"
    command: "bash -lc 'exec /home/udx/bin/run-scheduler.sh --interval=60'"
    autostart: true
    autorestart: true
  • Use one command string per service.
  • No args field in services.yaml.
  • Do not put provider references like azure/... in envs.
Runtime Services Reference

Env as Secrets

Define provider refs once in worker.yaml, then choose one auth path for your target environment.

Step 1 · Runtime config

Define secret refs in worker.yaml

Keep refs portable here. Deployment env vars can still override values. 

# /home/udx/.config/worker/worker.yaml
kind: workerConfig
version: udx.io/worker-v1/config
config:
  secrets:
    DB_PASSWORD: "gcp/my-project/db-password"

Step 2 · Auth path

Local keyless (recommended)

Set deployment service account once; CLI uses short-lived credentials.

Set service account in deploy.yml

service_account:
  email: "worker-sa@my-project.iam.gserviceaccount.com"

1) Sign in to Google Cloud

gcloud auth login

2) Create/update application default credentials

gcloud auth application-default login

3) Start deployment

worker run

Step 3 · Inside running container

Verify auth + secret resolution

Check auth state

worker auth status --format json

Resolve one reference

worker env resolve gcp/my-project/service-token

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)
Runtime Config Docs Authorization Docs GCP Auth Paths Kubernetes Auth/Deploy

Deployment Patterns

Keep deployment concerns outside runtime files: image, mounts, and env overrides.

1) Worker CLI

Use one deploy.yml across local and CI.

npm install -g @udx/worker-deployment
worker config
worker run --dry-run
worker run

2) Minimal deploy.yml

kind: workerDeployConfig
version: udx.io/worker-v1/deploy
config:
  image: "usabilitydynamics/udx-worker:latest"
  volumes:
    - "./.config/worker:/home/udx/.config/worker:ro"
  command: "worker"
  args:
    - "service"
    - "list"

3) Runtime troubleshooting

On host

Open shell in running container

worker run run-it

Inside container shell

Inspect services

worker service list

Stream logs

worker service logs firebase --tail 100 --follow

4) Kubernetes

Mount services.yaml and optional worker.yaml via ConfigMap at /home/udx/.config/worker. Use cluster workload identity/service account for cloud access.

Deployment env vars (plain values or provider refs like gcp/<project>/<secret>) override worker.yaml across all deployment types. 

# Kubernetes deployment pattern
spec:
  serviceAccountName: worker-runtime
  containers:
    - name: worker
      volumeMounts:
        - name: worker-config
          mountPath: /home/udx/.config/worker
      env:
        - name: ES_PASSWORD
          value: "gcp/staging-project/es-password"
  volumes:
    - name: worker-config
      configMap:
        name: worker-runtime-config
Deploy Docs Worker Deploy CLI Kubernetes Deploy GCP Auth

CLI Reference

Most-used commands with one-line intent.

On host (@udx/worker-deployment)

Preview generated container command

Safe check before execution.

worker run --dry-run

Run deployment from deploy.yml

Starts container with resolved config/mounts.

worker run

Inside container shell

List supervised services

Quick health/visibility check.

worker service list

Stream service logs

Follow one service during startup or incident.

worker service logs <service> --tail 100 --follow

Check provider auth status

Use JSON output for scripts and CI checks.

worker auth status --format json
Worker CLI Reference worker-deployment Docs

Image Selection

Start with base image. Move to child images only when your runtime needs preinstalled language tooling. 

worker images --all
Image Best For App Mount Links
udx-worker Generic automation and custom process stacks /home/udx or custom Repo · Hub
udx-worker-nodejs Node.js services and CI jobs /usr/src/app Repo · Hub
udx-worker-php PHP workloads with NGINX + PHP-FPM /var/www Repo · Hub

Quick decision

  • udx-worker: default for most workloads.
  • udx-worker-nodejs: choose when Node.js toolchain is required.
  • udx-worker-php: choose when PHP-FPM + NGINX stack is required.

Development flow (local)

Use one deploy file, edit image + mounts, then validate and run.

1) Create/update deploy template

worker config

2) Edit deploy.yml to set your image and app mount

config:
  image: "usabilitydynamics/udx-worker-nodejs:latest"
  volumes:
    - ".:/usr/src/app"

3) Preview and run

worker run --dry-run
worker run
Base Image Repo Node.js Image Repo PHP Image Repo Docker Hub Org

Production Checklist

  • Pin semantic image tags in CI/CD, avoid floating tags in critical pipelines.
  • Mount runtime config read-only whenever possible.
  • Use least-privilege cloud credentials and rotate them regularly.
  • Keep secret references in worker.yaml, not hardcoded values in images.
  • Use JSON output for scripted checks (--format json).
  • Monitor worker service status and logs as part of deployment health checks.
  • Separate high-trust workloads into separate worker deployments.

Contributing

For base and child image contributions, follow repo-specific standards and keep docs/tests updated.

License

UDX Worker images and related tooling are MIT-licensed.

Primary LICENSE All UDX repos