UDX Worker Documentation

UDX Worker is designed to provide a secure and efficient environment for running your services while maintaining best practices in DevSecOps, with integrated support for multiple secret managers and robust service management capabilities.

View Source Code

Getting Started

Prerequisites

Before using the UDX Worker Image, ensure you have the following prerequisites installed:

Docker
A text editor for modifying configuration files
Git (if you are cloning the repository)

Note: If you are using secrets in your project, ensure you have access to your chosen secret manager. UDX Worker supports multiple secret managers, including:

Azure Key Vault

AWS Secrets Manager

Bitwarden Secret Manager

Google Cloud Secret Manager

Preparation

Create a directory on your host machine for your project.

mkdir -p path/to/your-project-name

Note: This directory will be mounted to /home/udx in the container and is essential for:

Storing your configuration files:

worker.yaml - main worker configuration that manages environment variables and enables secure access to various secret managers.

services.yaml - this configuration allows you to manage scripts as a service.

Persisting worker data between container restarts

Running your own application within the container by mounting your project directory

Installation

There are several ways to install and run the UDX Worker. Choose the method that best suits your environment:

Using Docker Desktop

Search for udx-worker using the search interface and hit "Run" button.

You will be prompted to configure the container.

Give your container a name relevant to your project
Set up volume mounting to /home/udx
Set environment variables or configure worker.yaml
Run the container

Using Docker CLI

Use the following command to deploy the UDX Worker:

docker run -d \ 
  -v $/path/to/your/project:/home/udx \ 
  usabilitydynamics/udx-worker:latest

Note: The image will be pulled from Docker Hub if it's not already present locally.

Configuration

Core Components

The UDX Worker consists of several core components that work together to provide a seamless automation experience:

Worker Configuration: The worker.yaml file is the main configuration file for environment variables and secrets. See the Configuration Structure section below for detailed examples.
Service Configuration: The services.yaml file defines service behavior and is managed by Supervisor for reliable process management. See the Configuration Structure section below for detailed examples.

Configuration Structure

UDX Worker uses a standardized configuration structure located in /home/udx. This directory contains all necessary configuration files for the worker and its services.

Directory Structure

/home/udx/
├── worker.yaml      # Main worker configuration
├── services.yaml    # Service definitions
└── credentials/    # Authentication credentials
    ├── aws/
    ├── azure/
    └── bitwarden/

Worker Configuration (worker.yaml)

The main configuration file supports environment variables and secrets management:

kind: workerConfig
version: udx.io/worker-v1/config
config:
  env:
    AZURE_CLIENT_ID: "12345678-1234-1234-1234-1234567890ab"
    AZURE_TENANT_ID: "abcdef12-3456-7890-abcd-ef1234567890"
  secrets:
    APP_CLIENT_SECRET: "azure/kv-example/clientSecret"

Service Configuration (services.yaml)

Define and manage services using Supervisor integration:

kind: workerService
version: udx.io/worker-v1/service
services:
  - name: "example-service"
    command: "python /app/service.py"
    autostart: true
    autorestart: true
    environment:
      - "ENV=production"

Service Configuration Options:

autostart: Start service when container starts
autorestart: Restart policy (true, false, unexpected)
stopasgroup: Stop all child processes
environment: Service-specific environment variables

Authentication Modules

UDX Worker supports multiple authentication providers with file-based credentials:

AWS Authentication

# /home/udx/credentials/aws/credentials.yaml
{
  "aws_access_key_id": "YOUR_ACCESS_KEY",
  "aws_secret_access_key": "YOUR_SECRET_KEY",
  "region": "us-west-2"
}

Azure Authentication

# /home/udx/credentials/azure/credentials.yaml
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "tenant_id": "YOUR_TENANT_ID"
}

Bitwarden Authentication

# /home/udx/credentials/bitwarden/credentials.yaml
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "master_password": "YOUR_MASTER_PASSWORD"  # Optional
}

Security Best Practices:

Use environment-specific credentials files
Implement proper file permissions (600)
Consider using Docker secrets in swarm mode
Rotate credentials regularly
Monitor access patterns and audit logs

Validation and Troubleshooting

Use the following commands to validate your configuration:

# Validate configuration syntax
docker exec -it [container-id] worker config validate

# Test authentication
docker exec -it [container-id] worker auth test

# View effective configuration
docker exec -it [container-id] worker config view

# Check service status
docker exec -it [container-id] worker service status

Environment Variables

Configuration through environment variables:

# Core settings
UDX_WORKER_MODE=production
UDX_LOG_LEVEL=info

# Integration settings
UDX_CLOUD_PROVIDER=azure
UDX_REGION=us-west-2

Secrets Management

How to configure and manage secrets:

# Example secrets configuration
secrets:
  API_KEY: "azure/kv-example/api-key"
  DB_PASSWORD: "aws/sm/database/password"

CLI Commands

Service Management

# List all services
worker service list

# Check service status
worker service status <service_name>

# View service logs
worker service logs <service_name>

# Start/stop/restart service
worker service start <service_name>
worker service stop <service_name>
worker service restart <service_name>

Service Management

Service Overview

Managing services in UDX Worker:

Service lifecycle management
Health checks
Auto-recovery

Service Commands

Basic Service Management

# List all services
worker service list

# Check service status
worker service status

# Start/Stop/Restart services
worker service start <service_name>
worker service stop <service_name>
worker service restart <service_name>

CLI Reference

Command Overview

UDX Worker provides a comprehensive CLI for managing your services and configuration.

Environment Commands

# View environment variables
worker env list

# Set environment variable
worker env set KEY=VALUE

# Remove environment variable
worker env unset KEY

Configuration Commands

# Validate configuration
worker config validate

# View current configuration
worker config view

Troubleshooting

Common Issues

Solutions to frequently encountered problems:

Connection issues
Configuration errors
Permission problems

Debugging Guide

Tools and techniques for debugging:

Log analysis
Diagnostic commands
Troubleshooting procedures

Recovery Procedures

Steps for recovering from common failures:

Service recovery
Data recovery
System restoration

Logs & Diagnostics

# View service logs
worker service logs <service_name>

# View system logs
worker logs

# Export diagnostics
worker diagnostics export