usabilitydynamics/udx-worker repository overview

⁠UDX Worker

Secure, containerized environment for DevSecOps automation and repeatable service execution.

⁠Quick Reference

• Where to get help: https://udx.dev/worker⁠
• Source: https://github.com/udx/worker⁠
• Dockerfile: https://github.com/udx/worker/blob/latest/Dockerfile⁠

⁠Supported Tags

• latest
• Semantic version tags (recommended for CI/CD pinning)

⁠What It Is

UDX Worker is a base image for running long-lived services and automation tasks in a consistent, secure container runtime. It supports structured runtime configuration and cloud credential injection while keeping deployment logic external to the image.

⁠Highlights

• Runs as a non-root udx user by default.
• Structured runtime config via worker.yaml and services.yaml.
• Built-in support for cloud credential injection (Azure, AWS, GCP).
• Consistent deployment across local machines, CI/CD, and Kubernetes.

⁠Quick Start

⁠1) Run a Simple Service

mkdir -p my-worker/.config/worker
cd my-worker

cat > index.sh <<'SH'
#!/bin/bash
echo "Starting service..."
trap 'echo "Shutting down..."; exit 0' SIGTERM
while true; do
  echo "[$(date)] Service running..."
  sleep 5
done
SH
chmod +x index.sh

cat > .config/worker/services.yaml <<'YAML'
kind: workerService
version: udx.io/worker-v1/service
services:
  - name: "index"
    command: "/home/udx/index.sh"
    autostart: true
    autorestart: true
YAML

docker run -d \
  --name udx-worker \
  -v "$(pwd):/home/udx" \
  usabilitydynamics/udx-worker:latest

docker logs -f udx-worker

⁠2) Add Runtime Secrets

cat > .config/worker/worker.yaml <<'YAML'
kind: workerConfig
version: udx.io/worker-v1/config
config:
  secrets:
    API_KEY: "azure/key-vault/api-key"
    DB_PASS: "aws/secrets/database"
YAML

AZURE_CREDS=$(echo '{"client_id":"CLIENT_ID","client_secret":"CLIENT_SECRET","tenant_id":"TENANT_ID","subscription_id":"SUBSCRIPTION_ID"}' | base64)

docker run -d \
  --name udx-worker-secrets \
  -v "$(pwd)/.config/worker:/home/udx/.config/worker:ro" \
  -e AZURE_CREDS="${AZURE_CREDS}" \
  usabilitydynamics/udx-worker:latest

docker exec udx-worker-secrets worker auth verify

⁠Configuration Model

UDX Worker separates runtime configuration from deployment configuration.

• Runtime config (inside container):
  • worker.yaml (secrets, env, auth)
  • services.yaml (long-running services)
• Deployment config (outside container):
  • deploy.yml (image, mounts, command/args)

Runtime files are typically mounted into /home/udx/.config/worker/.

⁠Deployment With worker-deployment

The @udx/worker-deployment CLI standardizes deployment across laptops, CI/CD, and ephemeral hosts.

npm install -g @udx/worker-deployment
worker config   # generates deploy.yml
worker run      # runs with deploy.yml

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: "echo"
  args:
    - "Hello from deploy.yml"

⁠Kubernetes

For Kubernetes, store worker.yaml and services.yaml in ConfigMaps or Secrets and mount them into the container at /home/udx/.config/worker/.

⁠Supported Credential Env Vars

• AZURE_CREDS
• AWS_CREDS
• GCP_CREDS

Values can be JSON, Base64-encoded JSON, or a file path.

⁠Documentation

• Docs: https://udx.dev/worker⁠
• Docs (GitHub): https://github.com/udx/worker/tree/latest/docs⁠
• GitHub: https://github.com/udx/worker⁠
• Docker Hub: https://hub.docker.com/r/usabilitydynamics/udx-worker⁠

⁠License

MIT License. See https://github.com/udx/worker/blob/latest/LICENSE⁠.