Quick Start

TaskDaemon quick start guide

Quick Start

Run a persistent TaskDaemon instance and verify a Python handler from submission to completion.

Prerequisites

Docker must be installed and running. Check docker info; if it fails, start the Docker engine yourself before continuing. The polling example also uses curl and jq.

1. Create a Handler

mkdir taskdaemon-quickstart
cd taskdaemon-quickstart

Create handler.py:

import json
import sys

for line in sys.stdin:
    task = json.loads(line)
    name = task["task_data"].get("name", "World")
    print(json.dumps({
        "status": "success",
        "result": {"message": f"Hello, {name}!"},
    }), flush=True)

Create Dockerfile.handler:

FROM python:3.11-slim
COPY handler.py /app/
WORKDIR /app
CMD ["python", "-u", "handler.py"]

2. Build the Handler Image

docker build -f Dockerfile.handler -t my-greeter:latest .

3. Create Handler Config

Create handlers.toml:

[handlers.greet]
image = "my-greeter:latest"
instances = 2

4. Start TaskDaemon

docker run -d --name taskdaemon \
  -p 8080:8080 \
  -e DAEMON_DB_PATH=/data/tasks.db \
  -e DAEMON_BATCH_SIZE=5 \
  -v task-data:/data \
  -v "$(pwd)/handlers.toml:/app/handlers.toml:ro" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mshelia/taskdaemon:0.2.0-alpha

Use a validated image release, or build the current source. Inspect startup with docker logs taskdaemon. The CLI defaults to 2 workers. /health confirms queue access; the first submitted task also checks that the handler can initialize and respond.

5. Submit and Wait for a Result

This Bash script waits up to 60 seconds for daemon health and 120 seconds for task completion:

#!/usr/bin/env bash
set -euo pipefail

healthy=false
for ((i=0; i<60; i++)); do
  if curl -fsS http://localhost:8080/health | jq -e '.status == "healthy"' >/dev/null; then
    healthy=true
    break
  fi
  sleep 1
done
if [[ "$healthy" != true ]]; then
  echo "Daemon did not become healthy; inspect docker logs taskdaemon" >&2
  exit 1
fi

TASK_ID=$(curl -fsS -X POST http://localhost:8080/queue \
  -H "Content-Type: application/json" \
  -d '{"type":"greet","data":{"name":"TaskDaemon"}}' | jq -er '.task_id')

for ((i=0; i<120; i++)); do
  response=$(curl -fsS "http://localhost:8080/api/tasks/$TASK_ID")
  status=$(jq -r '.status' <<< "$response")
  case "$status" in
    completed) jq . <<< "$response"; exit 0 ;;
    failed) jq . <<< "$response"; exit 1 ;;
  esac
  sleep 1
done
echo "Task did not finish in 120 seconds: $TASK_ID" >&2
exit 1

A completed response includes result: {"message":"Hello, TaskDaemon!"}. Check status before interpreting a result; submission only acknowledges that the task was persisted.

6. Cleanup

docker stop taskdaemon
docker rm taskdaemon

The task-data volume remains so a replacement daemon can read the task history. Delete it only when you intentionally want to discard that data:

docker volume rm task-data

Next Steps

• Use the Python SDK for handler code
• See the Sample Project
• Configure monitoring
• Review batch size, retries, and leases