Skip to content
Klutch.sh Docs

Deploying uTask

Introduction

uTask (pronounced micro-task) is an automation engine developed by OVHcloud that enables declarative workflow orchestration through YAML-based task definitions. Instead of writing procedural automation scripts, you define what you want to accomplish, and uTask handles the execution, dependencies, retries, and error handling.

Built with Go for performance and reliability, uTask provides a web interface for monitoring tasks, a REST API for integration, and a plugin system for extending functionality. The engine excels at orchestrating complex multi-step processes that involve calling APIs, running scripts, and coordinating between services.

Key highlights of uTask:

  • Declarative Workflows: Define tasks in YAML with clear step dependencies
  • Built-in Plugins: HTTP calls, scripts, SSH commands, and more out of the box
  • Retry Logic: Automatic retries with configurable backoff strategies
  • State Management: Track task progress and resume from failures
  • Web Dashboard: Monitor running and completed tasks through a UI
  • REST API: Full API access for integration and automation
  • Variables and Templating: Dynamic values using Go templates
  • Conditional Execution: Run steps based on conditions
  • Parallel Execution: Execute independent steps simultaneously
  • Audit Logging: Complete history of task executions
  • Open Source: Licensed under Apache 2.0

This guide walks through deploying uTask on Klutch.sh using Docker, creating task templates, and orchestrating automated workflows.

Why Deploy uTask on Klutch.sh

Deploying uTask on Klutch.sh provides several advantages for workflow automation:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds uTask without complex configuration. Push to GitHub, and your automation engine deploys automatically.

Persistent Storage: Attach persistent volumes for task state and execution history. Your automation data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access and webhook endpoints.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to task templates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on task complexity and execution frequency.

Environment Variable Management: Securely store API keys and secrets through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for clean API and webhook URLs.

Always-On Availability: Your automation engine remains accessible 24/7 for scheduled and triggered tasks.

Prerequisites

Before deploying uTask on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and YAML syntax
  • Understanding of workflow automation concepts

Understanding uTask Architecture

uTask consists of several interconnected components:

Engine Core: The Go-based execution engine that processes task definitions and manages step execution.

PostgreSQL Database: Stores task definitions, execution state, and audit history. Required for persistence.

Task Templates: YAML files defining reusable workflow patterns with inputs and steps.

Plugins: Executors for different step types (HTTP, script, SSH, etc.).

Web Dashboard: React-based UI for monitoring and managing tasks.

REST API: Full API for creating, running, and monitoring tasks programmatically.

Task Template Structure

name: example-task
description: An example automation task
title_format: "Example: {{.input.name}}"


inputs:
  - name: name
    description: Name to process
    type: string
    required: true


steps:
  step-1:
    description: First step
    action:
      type: http
      configuration:
        url: "https://api.example.com/process"
        method: POST
        body: '{"name": "{{.input.name}}"}'


  step-2:
    description: Second step
    dependencies:
      - step-1
    action:
      type: echo
      configuration:
        output: "Processed: {{.step.step-1.output}}"

Preparing Your Repository

To deploy uTask on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

utask-deploy/
├── Dockerfile
├── config.yaml
├── templates/
│   └── example-task.yaml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for uTask:

FROM golang:1.21-alpine AS builder


# Install build dependencies
RUN apk add --no-cache git make


# Clone and build uTask
WORKDIR /build
RUN git clone --depth 1 https://github.com/ovh/utask.git .
RUN make build


FROM alpine:3.19


# Install runtime dependencies
RUN apk add --no-cache ca-certificates


# Create app directory and user
RUN adduser -D -u 1000 utask
WORKDIR /app


# Copy built binary
COPY --from=builder /build/utask /app/utask


# Copy configuration and templates
COPY config.yaml /app/config.yaml
COPY templates/ /app/templates/


# Create data directory
RUN mkdir -p /data && chown -R utask:utask /data /app


# Set user
USER utask


# Environment variables
ENV UTASK_CFG=/app/config.yaml


# Expose web/API port
EXPOSE 8081


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8081/health || exit 1


# Start uTask
CMD ["/app/utask"]

Configuration File

Create a config.yaml file:

# uTask Configuration


application_name: utask
admin_usernames:
  - admin


server:
  port: 8081
  bind: 0.0.0.0


database:
  type: postgres
  host: "${DB_HOST}"
  port: 5432
  user: "${DB_USER}"
  password: "${DB_PASSWORD}"
  database: "${DB_NAME}"
  ssl_mode: require


encryption_key: "${ENCRYPTION_KEY}"


plugins:
  - type: echo
  - type: http
  - type: script
  - type: subtask


templates_dir: /app/templates


executor:
  max_concurrent_executions: 10
  default_retry_max: 3


dashboard:
  enabled: true
  path_prefix: /ui

Example Task Template

Create templates/example-task.yaml:

name: http-request
description: Make an HTTP request and process the response
title_format: "HTTP Request to {{.input.url}}"


allowed_resolver_usernames:
  - admin


inputs:
  - name: url
    description: URL to request
    type: string
    required: true
  - name: method
    description: HTTP method
    type: string
    default: GET
  - name: headers
    description: Request headers
    type: object
    default: {}


steps:
  make-request:
    description: Execute HTTP request
    action:
      type: http
      configuration:
        url: "{{.input.url}}"
        method: "{{.input.method}}"
        headers: "{{.input.headers | toJson}}"
    retry_pattern: exponential_backoff


  process-response:
    description: Process the response
    dependencies:
      - make-request
    action:
      type: echo
      configuration:
        output:
          status: "{{.step.make-request.output.status}}"
          body: "{{.step.make-request.output.body}}"

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

VariableRequiredDefaultDescription
DB_HOSTYes-PostgreSQL hostname
DB_USERYes-Database username
DB_PASSWORDYes-Database password
DB_NAMEYes-Database name
ENCRYPTION_KEYYes-Key for encrypting sensitive data
UTASK_CFGNo/app/config.yamlConfiguration file path

Deploying uTask on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

    Set Up PostgreSQL Database

    uTask requires PostgreSQL. You can:

    • Deploy PostgreSQL on Klutch.sh
    • Use a managed PostgreSQL service (AWS RDS, Neon, etc.)

    Note your connection details for the environment variables.

    Generate Encryption Key

    Create a secure encryption key for sensitive data storage. Use a 32-character random string.

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add .
    git commit -m "Initial uTask deployment configuration"
    git remote add origin https://github.com/yourusername/utask-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Name it something descriptive like “utask” or “automation-engine”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your uTask repository.

    Configure HTTP Traffic

    uTask serves its API and dashboard over HTTP:

    • Select HTTP as the traffic type
    • Set the internal port to 8081

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    DB_HOSTYour PostgreSQL hostname
    DB_USERDatabase username
    DB_PASSWORDDatabase password
    DB_NAMEDatabase name
    ENCRYPTION_KEYYour generated encryption key

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /data5 GBApplication data and logs

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Build uTask from source
    • Create the container image
    • Start the automation engine
    • Provision an HTTPS certificate

    Access uTask

    Once deployed, access:

    • Dashboard: https://your-app.klutch.sh/ui
    • API: https://your-app.klutch.sh/api/v1

Creating Task Templates

Basic Task Structure

Every task template includes:

name: task-name
description: What this task does
title_format: "Task: {{.input.param}}"


inputs:
  - name: param
    type: string
    required: true


steps:
  step-name:
    action:
      type: plugin-type
      configuration:
        key: value

Available Plugins

PluginDescription
httpMake HTTP requests
scriptExecute shell scripts
echoOutput data (useful for debugging)
subtaskExecute another uTask task
sshExecute commands via SSH
emailSend email notifications

Step Dependencies

Define execution order with dependencies:

steps:
  first:
    action:
      type: echo
      configuration:
        output: "First step"


  second:
    dependencies:
      - first
    action:
      type: echo
      configuration:
        output: "After first: {{.step.first.output}}"

Conditional Execution

Run steps conditionally:

steps:
  check:
    action:
      type: http
      configuration:
        url: "https://api.example.com/status"


  on-success:
    dependencies:
      - check
    conditions:
      - type: check
        if:
          - value: "{{.step.check.output.status}}"
            operator: EQ
            expected: "200"
    action:
      type: echo
      configuration:
        output: "Success path"

Using the API

Create a Task

POST /api/v1/task
Content-Type: application/json


{
  "template_name": "http-request",
  "input": {
    "url": "https://api.example.com/data",
    "method": "GET"
  }
}

Get Task Status

GET /api/v1/task/{task_id}

List Tasks

GET /api/v1/task?template_name=http-request&state=DONE

Production Best Practices

Security Recommendations

  • Encryption Key: Use a strong, unique encryption key
  • Database Security: Use SSL for database connections
  • Access Control: Configure allowed usernames appropriately
  • Secret Management: Store sensitive values in environment variables

Performance Optimization

  • Concurrent Executions: Tune based on workload
  • Database Connection Pooling: Configure appropriate pool sizes
  • Template Optimization: Design efficient step structures
  • Resource Allocation: Scale based on task complexity

Monitoring

  • Health Checks: Monitor the health endpoint
  • Task Metrics: Track execution times and failure rates
  • Database Monitoring: Watch for performance issues
  • Log Analysis: Review execution logs regularly

Troubleshooting Common Issues

Database Connection Failures

Symptoms: uTask fails to start or loses connection.

Solutions:

  • Verify database credentials
  • Check network connectivity
  • Confirm SSL settings match database requirements
  • Review database logs

Task Execution Failures

Symptoms: Tasks fail during step execution.

Solutions:

  • Check step configurations
  • Verify external service availability
  • Review step logs for errors
  • Test with simpler task definitions

Template Errors

Symptoms: Templates fail to load or parse.

Solutions:

  • Validate YAML syntax
  • Check template variable references
  • Ensure all required fields are present
  • Review uTask logs for parse errors

Additional Resources

Conclusion

Deploying uTask on Klutch.sh gives you a powerful, declarative automation engine for orchestrating complex workflows. The combination of uTask’s YAML-based task definitions and Klutch.sh’s deployment simplicity means you can automate multi-step processes without managing infrastructure.

Whether you’re coordinating API calls, managing deployments, or automating operational tasks, uTask on Klutch.sh provides a reliable foundation for workflow automation that scales with your needs.