update docs

udx · Feb 21, 2025 · 6608394 · 6608394
1 parent 0460665
commit 6608394
Show file tree

Hide file tree

Showing 8 changed files with 733 additions and 255 deletions.
diff --git a/README.md b/README.md
@@ -1,86 +1,192 @@
-## UDX Worker
-
-The UDX Worker simplifies DevSecOps by providing a secure, containerized environment for handling secrets and running automation tasks. This repository contains the UDX Worker Docker image, designed for secure and reliable automation tasks based on 12-factor methodology. UDX Worker environments are ephemeral and adhere to zero-trust principles and methodology, ensuring maximum security and reliability.
-
-### Deployment
-
-1. Make sure Docker installed.
-
-2. Pull the Docker image:
+# UDX Worker
+
+[![Docker Pulls](https://img.shields.io/docker/pulls/usabilitydynamics/udx-worker.svg)](https://hub.docker.com/r/usabilitydynamics/udx-worker)
+[![License](https://img.shields.io/github/license/udx/worker.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-udx.dev-blue.svg)](https://udx.dev/worker)
+
+**Secure, containerized environment for DevSecOps automation**
+
+[Quick Start](#quick-start) •
+[Documentation](#documentation) •
+[Development](#development) •
+[Contributing](#contributing)
+
+## 🚀 Overview
+
+UDX Worker is a containerized solution that simplifies DevSecOps by providing:
+
+- 🔒 **Secure Environment**: Built on zero-trust principles
+- 🤖 **Automation Support**: Streamlined task execution
+- 🔑 **Secret Management**: Secure handling of sensitive data
+- 📦 **12-Factor Compliance**: Modern application practices
+- ♾️ **CI/CD Ready**: Seamless pipeline integration
+
+## 🏃 Quick Start
+
+### Prerequisites
+
+- Docker 20.10 or later
+- Make (for development)
+
+### Example 1: Simple Service
+
+```bash
+# 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
 
-```shell
-docker pull usabilitydynamics/udx-worker:latest
+# View service logs
+docker logs -f my-service
 ```
 
-3. Run the Docker container:
-
-```shell
+### Example 2: Secrets Management with Authorization
+
+```bash
+# Define secrets configuration
+cat > .config/worker/worker.yaml <<'EOF'
+kind: workerConfig
+version: udx.io/worker-v1/config
+config:
+  secrets:
+    API_KEY: "azure/key-vault/api-key"
+    DB_PASS: "aws/secrets/database"
+EOF
+
+# Create base64-encoded Azure credentials
+AZURE_CREDS=$(echo '{
+  "client_id": "your-client-id",
+  "client_secret": "your-client-secret",
+  "tenant_id": "your-tenant-id"
+}' | base64)
+
+# Run with cloud provider credentials
 docker run -d \
-  --name my-app \
-  -v $(pwd):/home/udx \
+  --name my-secrets \
+  -v "$(pwd)/.config/worker:/home/udx/.config/worker" \
+  -e AZURE_CREDS="${AZURE_CREDS}" \
   usabilitydynamics/udx-worker:latest
-```
 
-_Make sure to mount the current directory to `/home/udx` in the container._
+# Verify authorization and secrets
+docker exec my-secrets worker auth verify
+docker exec my-secrets worker env get API_KEY
+```
 
-### Development
+See [Authorization Guide](docs/authorization.md) for supported providers and credential formats (JSON, Base64, File Path).
 
-1. Clone the Repository
+### Development Setup
 
-```shell
+```bash
+# Clone and build
 git clone https://github.com/udx/worker.git
 cd worker
-```
+make build
 
-2. Build Image
+# Run example service
+make run VOLUMES="$(pwd)/src/examples/simple-service:/home/udx"
 
-```shell
-make build
+# View logs
+make log FOLLOW_LOGS=true
+
+# Run tests
+make test
 ```
 
-3. Start the container
+More examples available in [src/examples](src/examples).
 
-```shell
-make run
-```
+## 📚 Documentation
 
-_Interactively_
+### Core Concepts
+- [Authorization](docs/authorization.md) - Credential management
+- [Configuration](docs/config.md) - Worker setup
+- [Services](docs/services.md) - Service management
+- [CLI Reference](docs/cli.md) - Command line usage
 
-```shell
-make run-it
-```
+### Additional Resources
+- [Container Structure](docs/container-structure.md) - Directory layout
+- [Development Notes](docs/notes.md) - Best practices
+- [Git Tips](docs/git-help.md) - Version control helpers
+
+## 🛠️ Development
+
+```bash
+# Clone repository
+git clone https://github.com/udx/worker.git
+cd worker
+
+# Build image
+make build
 
-4. Run tests
+# Run container
+make run      # Detached mode
+make run-it   # Interactive mode
 
-```shell
+# Run tests
 make test
+
+# View all commands
+make help
 ```
 
-_For more details on available commands_
+## 🤝 Contributing
 
-```shell
-make
-```
+We welcome contributions! Here's how you can help:
 
-### Docs
+1. Fork the repository
+2. Create a feature branch
+3. Commit your changes
+4. Push to your branch
+5. Open a Pull Request
 
-- [Authorization](/docs/authorization.md)
-- [CLI](/docs/cli.md)
-- [Config](/docs/config.md)
-- [Git Help](/docs/git.md)
-- [Notes](/docs/notes.md)
-- [Services](/docs/services.md)
+Please ensure your PR:
+- Follows our coding standards
+- Includes appropriate tests
+- Updates relevant documentation
 
-### Resources
+## 🔗 Resources
 
 - [Docker Hub](https://hub.docker.com/r/usabilitydynamics/udx-worker)
 - [Documentation](https://udx.dev/worker)
-- [Marketing Page](https://udx.io/products/udx-worker)
+- [Product Page](https://udx.io/products/udx-worker)
+
+## 🎯 Custom Development
 
-### Contributing
+Need specific features or customizations?
+[Contact our team](https://udx.io/) for professional development services.
 
-Contributions are welcome! If you find any issues or have suggestions for improvements, please fork the repository and submit a pull request.
+## 📄 License
 
-### Custom Development
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-Looking for a unique feature for your next project? [Hire us!](https://udx.io/)
+---
+<div align="center">
+Built with ❤️ by <a href="https://udx.io">UDX</a>
+</div>
diff --git a/docs/CLI.md b/docs/CLI.md
@@ -1,91 +1,28 @@
 # UDX Worker CLI Documentation
 
-The UDX Worker provides a command-line interface for managing services, environment variables, and generating Software Bill of Materials (SBOM).
+The UDX Worker provides a command-line interface for managing services, environment variables, generating Software Bill of Materials (SBOM), and more.
 
-## Commands
+## Available Commands
 
-### Service Management
+| Command  | Description |
+|----------|-------------|
+| `auth`   | Manage authentication operations |
+| `config` | Manage configuration operations |
+| `env`    | Manage environment variables |
+| `health` | Monitor system health status |
+| `help`   | Show help for any command |
+| `sbom`   | Manage Software Bill of Materials |
+| `service`| Manage service operations |
+| `version`| Show version information |
 
-* `worker service list`
-  - Lists of configured services.
-  - Shows service name, status, PID, and uptime
+## Usage
 
-* `worker service status <service_name>`
-  - Displays detailed status of a service
-  - Shows service state, uptime, and process information
-
-* `worker service logs <service_name> [options]`
-  - Views service output logs
-  - Options:
-    - `--lines N`: Show last N lines (default: 20)
-    - `--nostream`: Show logs without following
-
-* `worker service errors <service_name> [options]`
-  - Views service error logs
-  - Options:
-    - `--lines N`: Show last N lines (default: 20)
-    - `--nostream`: Show logs without following    
-
-* `worker service config`
-  - Shows the services configuration settings
-  - Displays supervisor configuration for all services
-
-* `worker service start <service_name>`
-  - Starts a specified service
-  - Creates necessary log files and directories
-
-* `worker service stop <service_name>`
-  - Stops a specified service
-  - Service can be restarted later
-
-* `worker service restart <service_name>`
-  - Restarts a specified service
-  - Equivalent to stop followed by start
-
-### Environment Variables
-
-* `worker env set <key> <value>`
-  - Sets an environment variable
-  - Variable will be available to all services
-
-* `worker env get [key]`
-  - Retrieves environment variable(s)
-  - If key is provided, shows specific variable
-  - If no key, shows all environment variables
-
-### Software Bill of Materials
-
-* `worker sbom generate`
-  - Generates container Software Bill of Materials
-  - Lists all installed packages with:
-    - Package name
-    - Version
-    - Architecture
-
-## Examples
+To see detailed help and usage information for any command, run it without arguments:
 
 ```bash
-# View service status
-worker service status my_service
-
-# Get last 100 lines of logs without following
-worker service logs my_service --lines=100 --nostream
-
-# Set and verify environment variable
-worker env set MY_VAR "my value"
-worker env get MY_VAR
-
-# Generate SBOM
-worker sbom generate
-```
-
-## Exit Codes
-
-- 0: Command completed successfully
-- 1: Command failed or invalid usage
-
-## Notes
+# Show auth command help
+worker auth
 
-- All commands use logging levels: INFO, DEBUG, WARN, ERROR
-- Service logs are stored in `/var/log/supervisor/`
-- Configuration files are in `/etc/supervisord.conf`
+# Show service command help
+worker service
+```