Container runtime foundation for UDX automation images.
Quick Start | Documentation | Development
UDX Worker is a base container image for automation workloads that need predictable runtime config, secret references, and process supervision.
It provides:
worker.yamlfor runtime env values, secret references, and opt-in runtime output.services.yamlfor supervised processes inside the container.- Secret reference resolution from AWS, Azure, and Google Cloud after provider auth exists.
- A shared CLI for inspecting and re-applying container runtime config.
- A stable base for child images that add workload-specific tools.
- Docker 20.10 or later
- Make (for development)
# Create project structure
mkdir -p my-worker/.config/worker
cd my-worker
# Create a simple service script
cat > index.sh <<'EOF'
#!/bin/bash
echo "Starting service..."
trap 'echo "Shutting down..."; exit 0' SIGTERM
while true; do
echo "[$(date)] Service running..."
sleep 5
done
EOF
chmod +x index.sh
# Create service configuration
cat > .config/worker/services.yaml <<'EOF'
kind: workerService
version: udx.io/worker-v1/service
services:
- name: "index"
command: "/home/udx/index.sh"
autostart: true
autorestart: true
EOF
# Run the worker
docker run -d \
--name my-service \
-v "$(pwd):/home/udx" \
usabilitydynamics/udx-worker:latest
# View service logs
docker logs -f my-service# Define secrets configuration
cat > .config/worker/worker.yaml <<'EOF'
kind: workerConfig
version: udx.io/worker-v1/config
config:
secrets:
API_KEY: "gcp/my-project/api-key"
DB_PASS: "aws/database-password/us-west-2"
EOF
# Run with provider auth injected by the host/platform
docker run -d \
--name my-secrets \
-v "$(pwd)/.config/worker:/home/udx/.config/worker" \
usabilitydynamics/udx-worker:latest
# Verify the resolved environment without printing the secret value
docker exec my-secrets sh -lc 'worker env show --filter API_KEY --format json | jq -e '\''has("API_KEY") and .API_KEY != ""'\'' >/dev/null'See Secrets for secret references and provider auth boundaries.
Deployment uses the host-native tool for the target environment. Mount runtime config into the container and pass provider credentials, workload identity, or secret references through the platform.
docker run --rm \
-v "$(pwd)/.config/worker:/home/udx/.config/worker:ro" \
-e API_KEY="gcp/my-project/api-key" \
usabilitydynamics/udx-worker:latestFor Kubernetes, mount worker.yaml and services.yaml through ConfigMaps or Secrets and deploy the image with normal Kubernetes manifests.
# Clone and build
git clone https://github.com/udx/worker.git
cd worker
make build
# Run example service
make run VOLUMES="$(pwd)/src/examples/simple-service:/home/udx"
# View logs
make log FOLLOW_LOGS=true
# Run tests
make testMore examples available in src/examples/README.md.
- CLI - runtime inspection and re-apply commands
- Config -
worker.yaml, env values, runtime output - Secrets - secret references and provider auth boundaries
- Services -
services.yamlprocess config - Deployment - Docker, Kubernetes, and CI usage
- Runtime Output - redacted runtime contract capture
- Development - Build, test, and child image workflow
- Rabbit CI repository configuration - generated GitHub delivery metadata
- Reference Docs - provider auth options and container structure
- Examples - Runnable samples
# Clone repository
git clone https://github.com/udx/worker.git
cd worker
# Build image
make build
# Run container
make run # Detached mode
make run-it # Interactive mode
# Run tests
make test
# View all commands
make helpThe Docker dependency updater runs daily at 05:00 UTC and can also be started manually from GitHub Actions. It probes current APT versions, inventories Dockerfile ARG and URL pins, and opens a Dockerfile-only pull request when an update is available. An open updater pull request prevents duplicate runs.
Need specific features or customizations? Contact our team for professional development services.
This project is licensed under the MIT License - see the LICENSE file for details.