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 -dOne 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:latestFrom source. Stores its data in ./data:
cargo run -p valka-server| Service | Port | Description |
|---|---|---|
| REST API + Dashboard | 8989 | HTTP API, web UI, health and metrics |
| gRPC API | 50051 | Worker 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 another5. 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: storage backends, the Docker image and configuration
- Clustering: run several nodes on one bucket
- Deployment: production setups, health checks, alerts and the full configuration reference
- SDK Documentation: choose your language and start building