Installation & Configuration

Docker Compose (Recommended)

Create a docker-compose.yml file and start the services:

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
    restart: unless-stopped
    shm_size: 128mb

  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"
    restart: unless-stopped

volumes:
  pgdata:

docker compose up -d

This starts PostgreSQL 17 and the Valka server. The REST API, web dashboard, and gRPC endpoint are ready immediately.

Service	Default Port	Description
HTTP (REST + Dashboard)	`8989`	REST API, SSE events, Prometheus metrics, web dashboard
gRPC	`50051`	Worker connections, client SDKs, event/log streams

Docker Image

You can also run the Valka server image directly with an external PostgreSQL instance:

docker run -d \
  -e VALKA_DATABASE_URL=postgresql://user:pass@host:5432/valka \
  -p 8989:8989 \
  -p 50051:50051 \
  ghcr.io/iwhitebird/valka:latest

The image includes the Valka server, CLI tool, and the web dashboard. It runs as a non-root user (UID 1001) and includes curl for health checks.

Configuration

Valka uses layered configuration via Figment:

Priority (highest wins): environment variables > valka.toml > defaults

Environment Variables

Variable	Default	Description
`VALKA_DATABASE_URL`	-	PostgreSQL connection string (required)
`VALKA_DATABASE__MAX_CONNECTIONS`	`20`	Connection pool size
`VALKA_GRPC_ADDR`	`0.0.0.0:50051`	gRPC listen address
`VALKA_HTTP_ADDR`	`0.0.0.0:8989`	REST/HTTP listen address
`RUST_LOG`	`valka=info,tower_http=info`	Log level filter

All configuration values can be set via environment variables with the VALKA_ prefix and __ for nested keys. See the full configuration reference for all options.

Configuration File

Mount a valka.toml into the container at /etc/valka/ and pass its path as the first argument:

docker run -d \
  -v ./valka.toml:/etc/valka/valka.toml:ro \
  -p 8989:8989 \
  -p 50051:50051 \
  ghcr.io/iwhitebird/valka:latest \
  /etc/valka/valka.toml

valka.toml

[database]
url = "postgresql://valka:valka@postgres:5432/valka"
max_connections = 20

[server]
grpc_addr = "0.0.0.0:50051"
http_addr = "0.0.0.0:8989"

[scheduler]
lease_duration_secs = 300
reaper_interval_secs = 30
retry_interval_secs = 10

Database

Valka requires PostgreSQL 14+ (17 recommended). Migrations run automatically on server startup, no manual setup required.

Tables

Table	Purpose
`tasks`	Task metadata, state, and input/output
`task_runs`	Individual execution attempts
`task_logs`	Structured log entries per run
`dead_letter_queue`	Tasks that exhausted retries
`workers`	Registered worker connections
`task_signals`	Signals sent to running tasks

Health Check

The server exposes a health endpoint for container orchestrators:

curl http://localhost:8989/healthz
# Returns: "ok" (200)

Installation & Configuration

On this page