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
- Development - Build, test, and child image workflow
- 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 helpNeed 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.