Quick Start

Prerequisites

Docker and Docker Compose

1. Start Valka

Create a docker-compose.yml file:

docker-compose.yml

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: valka
      POSTGRES_PASSWORD: valka
      POSTGRES_DB: valka
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U valka"]
      interval: 5s
      timeout: 5s
      retries: 5

  valka:
    image: ghcr.io/iwhitebird/valka:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      VALKA_DATABASE_URL: postgresql://valka:valka@postgres:5432/valka
      VALKA_GRPC_ADDR: "0.0.0.0:50051"
      VALKA_HTTP_ADDR: "0.0.0.0:8989"
      RUST_LOG: valka=info,tower_http=info
    ports:
      - "50051:50051"
      - "8989:8989"

volumes:
  pgdata:

Start the services:

docker compose up -d

This starts PostgreSQL and the Valka server. Migrations run automatically on first boot.

Service	Port	Description
REST API + Dashboard	`8989`	HTTP API and web UI
gRPC API	`50051`	Worker connections and client SDK

2. Open the Dashboard

Visit http://localhost:8989 to access the web dashboard. You'll see real-time monitoring of tasks, workers, and events.

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 task will appear 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.

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

Installation & Configuration: configuration options and environment variables
Deployment: production deployment with clustering, PgBouncer, and Kubernetes
SDK Documentation: choose your language and start building