valka

Quick Start

Get Valka running in minutes, with nothing but Docker.

Prerequisites

  • Docker and Docker Compose, or a Rust toolchain (1.89+)

Valka needs no database and no broker. It stores everything in an S3-compatible bucket, or in a local directory when you run a single node.

1. Start Valka

Pick one of these.

Docker Compose (recommended). Starts an S3-compatible store and one Valka node built from source:

git clone https://github.com/IWhitebird/Valka.git && cd Valka
docker compose up -d

One container, local directory. No object store at all; the data lives in a Docker volume:

docker run -d --name valka \
  -p 8989:8989 -p 50051:50051 \
  -v valka-data:/var/lib/valka \
  ghcr.io/iwhitebird/valka:latest

From source. Stores its data in ./data:

cargo run -p valka-server
ServicePortDescription
REST API + Dashboard8989HTTP API, web UI, health and metrics
gRPC API50051Worker connections and client SDKs

With Docker Compose you also get the store's S3 API on 9000 and its web console on 9001 (minioadmin / minioadmin).

2. Open the Dashboard

Visit http://localhost:8989 to open the web dashboard. It shows tasks, workers, events and the cluster in real time.

3. Create a Task

Use the REST API to create your first task:

curl -X POST http://localhost:8989/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task_name": "send-welcome-email",
    "queue_name": "emails",
    "input": {"to": "user@example.com", "subject": "Welcome!"}
  }'

The answer comes back once the task is durable. It shows up in the dashboard with status PENDING.

4. Write a Worker

Install the SDK for your language and connect a worker:

import { ValkaWorker, type TaskContext } from "@valka/sdk";

const worker = ValkaWorker.builder()
  .name("email-worker")
  .serverAddr("localhost:50051")
  .queues(["emails"])
  .concurrency(4)
  .handler(async (ctx: TaskContext) => {
    const input = ctx.input<{ to: string; subject: string }>();
    ctx.log(`Sending email to ${input.to}...`);
    // your logic here
    return { status: "sent" };
  })
  .build();

await worker.run();

See the SDK documentation for Rust, Python, and Go examples. From a clone of the repository you can also run the Rust examples:

cargo run -p valka-examples --example worker     # in one terminal
cargo run -p valka-examples --example producer   # in another

5. Monitor

Head back to the dashboard at http://localhost:8989 to watch tasks flow through the system in real time, from PENDING to RUNNING to COMPLETED.

Next Steps

On this page