UDX Worker Documentation

A secure, containerized environment for DevSecOps automation with integrated support for multiple secret managers and robust service management capabilities.

View on GitHub Docker Hub

🔐 Secrets Management

Secure cloud provider integration for managing sensitive data

⚙️ Easy Configuration

Simple YAML-based configuration for services and environment variables

🚀 Service Management

Run and monitor multiple services with user-friendly configuration

Prerequisites

  • Docker installed and running
  • Basic understanding of YAML configuration
  • Access to cloud provider credentials (optional)

Project Structure

Create the following directory structure for your UDX Worker project: 

my-project/
├── .config/
│   └── worker/
│       ├── worker.yaml    # Worker configuration
│       └── services.yaml  # Services configuration
└── index.sh              # Your service script

Worker Configuration

Configure worker settings and environment variables: 

# /home/udx/.config/worker/worker.yaml
kind: workerConfig
version: udx.io/worker-v1/config
config:
  env:
    NODE_ENV: "production"
    DEBUG: "true"
  secrets:
    API_KEY: "azure/key-vault/api-key"
    DB_PASS: "aws/secrets/database"

📖 See the Worker Configuration Guide for detailed documentation.

Services Configuration

Define your services in the services configuration file: 

# /home/udx/.config/worker/services.yaml
kind: workerService
version: udx.io/worker-v1/service
services:
  - name: "web-server"
    command: "sh /home/udx/index.sh"
    autostart: true
    autorestart: true
    envs:
      - "PORT=8080"
      - "DEBUG=true"

📖 See the Services Configuration Guide for detailed documentation.

Authorization

UDX Worker supports multiple cloud providers and services through environment-based credential management.

Credential Formats

Credentials can be provided in three formats:

JSON Format

Direct configuration using plain JSON string

Base64 Format

Secure environment variables using base64-encoded JSON

File Path Format

Local development using path to JSON file

Supported Providers

Set the appropriate environment variable for your cloud provider when deploying:

Azure Key Vault

AZURE_CREDS

AWS Secrets Manager

AWS_CREDS

Google Cloud Platform

GCP_CREDS

Bitwarden

BITWARDEN_CREDS

💡 Tip: These variables support JSON, Base64, or File Path formats as described above.

Security Best Practices

  • Never commit credentials to version control
  • Use base64 encoding for sensitive environment variables
  • Regularly rotate cloud provider credentials
  • Implement proper access controls and permissions
  • Verify authorization status after deployment

Deployment

Deploy and manage your UDX Worker instance using Docker. 

# Pull the latest image
docker pull usabilitydynamics/udx-worker:latest

# Run the container
docker run -d \
  --name worker-container \
  -v "$(pwd):/home/udx" \
  --env-file .env \
  usabilitydynamics/udx-worker:latest

Deployment Checklist

  • Ensure proper volume mounts for configuration
  • For secrets fetching, ensure authorization environment variables are set

CLI Commands

UDX Worker provides a command-line interface for managing services, environment variables, and more.

Command Description
worker auth Manage authentication operations
worker config Manage configuration operations
worker env Manage environment variables
worker health Monitor system health status
worker sbom Manage Software Bill of Materials
worker service Manage service operations
worker version Show version information

Common Usage

Get help for any command: 

worker auth     # Show auth command help
worker service  # Show service command help

Development

UDX Worker serves as a secure base image for developing specialized container images. It provides a robust foundation with built-in security features, secret management, and service orchestration.

Specialized Images

PHP Worker

Optimized for PHP applications with built-in composer and common extensions

GitHub Docker Hub

Node.js Worker

Tailored for Node.js applications with npm and yarn support

GitHub Docker Hub

Creating Custom Images

Build your own specialized image using UDX Worker as the base: 

# Use UDX Worker as base image
FROM usabilitydynamics/udx-worker:latest

# Add your custom dependencies and configurations
RUN apt-get update && apt-get install -y your-package

# Copy your services
COPY ./services $HOME/.config/worker/services.yaml

# Configure environment
COPY ./config/worker.yaml $HOME/.config/worker/worker.yaml

Security

We take security seriously. If you discover a security vulnerability, please follow our responsible disclosure process:

  • Email security issues to security@udx.io
  • Do not disclose the issue publicly until we've addressed it
  • Provide detailed information about the vulnerability

See our Security Policy for more details.

Contributing

We welcome contributions! Here's how you can help:

  • Fork the repository
  • Create a feature branch
  • Submit a pull request with tests

Please read our Contributing Guidelines before submitting PRs.

License

UDX Worker is licensed under the MIT License. See the LICENSE file for details.