Skip to Content
Getting StartedDocker Deployment

Docker Deployment

KalamDB publishes jamals86/kalamdb:latest on Docker Hub. The image includes kalamdb-server, kalam-cli, and a kalam symlink. The server listens on port 2900 inside the container.

Note: Some older Docker Hub overview text references port 8080 or the kalamstack GitHub org. The commands below match the current image. Canonical Hub readme source: docker/REPO-README.md in the KalamDB repo.

Quick start — copy-paste

Run a single-node server on host port 2900, bootstrap auth, and log in:

BASH
docker run -d --name kalamdb -p 2900:2900 \  -e KALAMDB_SERVER_HOST=0.0.0.0 \  -e KALAMDB_JWT_SECRET="$(openssl rand -base64 32)" \  -e KALAMDB_ALLOW_REMOTE_SETUP=true \  -v kalamdb_data:/data \  jamals86/kalamdb:latest sleep 5curl -sS http://127.0.0.1:2900/v1/api/auth/status curl -sS -X POST http://127.0.0.1:2900/v1/api/auth/setup \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}' curl -sS -X POST http://127.0.0.1:2900/v1/api/auth/login \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!"}'

Save the access_token from the login response.

Verify from the host with auth/status (recommended). The /v1/api/healthcheck endpoint is localhost-only when reached through Docker port publishing — use this from inside the container instead:

BASH
docker exec kalamdb wget -qO- http://127.0.0.1:2900/v1/api/healthcheck

Admin UI: http://127.0.0.1:2900/ui — log in as admin / AdminPass123!.

Useful environment variables for local Docker runs:

VariablePurpose
KALAMDB_SERVER_HOSTBind address inside the container — use 0.0.0.0 when publishing ports
KALAMDB_JWT_SECRETJWT signing secret — use at least 32 characters in shared environments
KALAMDB_ALLOW_REMOTE_SETUPAllow first-time auth setup from the host when running in Docker
KALAMDB_SECURITY_CORS_ALLOWED_ORIGINSCORS origins for the Admin UI (compose files default to * for local demos)

Avoid KALAMDB_ROOT_PASSWORD for first-time Docker setup on the host: it can mark the server as configured while host login still fails. Use POST /v1/api/auth/setup instead (as in the quick start above).

Single node with Docker Compose

Download the compose file, create a compatible server.toml (the checked-in docker/run/single/server.toml in the KalamDB repo is missing required sections for current server builds), then start:

BASH
mkdir kalamdb-docker && cd kalamdb-dockercurl -fsSL https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/single/docker-compose.yml -o docker-compose.yml cat > server.toml <<'EOF'[server]host = "0.0.0.0"port = 2900 [storage]data_path = "/data" [limits] [logging]level = "info"logs_path = "/data/logs"log_to_console = trueformat = "json" [performance] [auth]jwt_secret = "docker-compose-placeholder-secret-32c" [security.cors]allowed_origins = ["*"] [rate_limit]max_queries_per_sec = 1000000max_messages_per_sec = 10000000max_subscriptions_per_user = 100000max_auth_requests_per_ip_per_sec = 20000000max_connections_per_ip = 100000max_requests_per_ip_per_sec = 20000000request_body_limit_bytes = 104857600ban_duration_seconds = 300enable_connection_protection = trueEOF KALAMDB_JWT_SECRET="$(openssl rand -base64 32)" KALAMDB_PORT=2900 docker compose up -d

By default the compose file maps ${KALAMDB_PORT:-8088}:2900. Setting KALAMDB_PORT=2900 publishes the API at http://127.0.0.1:2900.

Bootstrap and verify:

BASH
curl -sS http://127.0.0.1:2900/v1/api/auth/statuscurl -sS -X POST http://127.0.0.1:2900/v1/api/auth/setup \  -H 'Content-Type: application/json' \  -d '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}'

Friendly alias for the compose file only: kalamdb.org/docker-compose.yml  redirects to the GitHub source. You still need a compatible server.toml beside it.

3-node cluster

BASH
mkdir kalamdb-cluster && cd kalamdb-clustercurl -fsSL https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/cluster/docker-compose.yml -o docker-compose.ymlKALAMDB_JWT_SECRET="$(openssl rand -base64 32)" docker compose up -d

Default host ports:

NodeHTTP APIRaft gRPC
node 180819091
node 280829092
node 380839093

Verify node 1 from the host:

BASH
curl http://127.0.0.1:8081/v1/api/auth/status

Windows PowerShell

docker run with bootstrap:

powershell
docker run -d --name kalamdb -p 2900:2900 `  -e KALAMDB_SERVER_HOST=0.0.0.0 `  -e KALAMDB_JWT_SECRET="$([Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 })))" `  -e KALAMDB_ALLOW_REMOTE_SETUP=true `  -v kalamdb_data:/data `  jamals86/kalamdb:latest Start-Sleep -Seconds 5Invoke-RestMethod http://127.0.0.1:2900/v1/api/auth/status Invoke-RestMethod -Method Post http://127.0.0.1:2900/v1/api/auth/setup `  -ContentType "application/json" `  -Body '{"user":"admin","password":"AdminPass123!","root_password":"RootPass123!"}'

Compose (after creating docker-compose.yml and the server.toml from the single-node section above):

powershell
$env:KALAMDB_JWT_SECRET = [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))$env:KALAMDB_PORT = "2900"Invoke-WebRequest https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/single/docker-compose.yml -UseBasicParsing -OutFile docker-compose.ymldocker compose up -d

CLI inside the container

The image ships with kalam and kalam-cli:

BASH
docker exec kalamdb kalam --versiondocker exec -it kalamdb kalam --url http://127.0.0.1:2900 --user admin --password

CLI state defaults to /data/.kalam inside the container so credentials persist with the /data volume.

Persistence and cleanup

Data is stored under /data in the container. The quick-start docker run command uses the named volume kalamdb_data.

BASH
docker logs -f kalamdb          # view logsdocker stop kalamdb             # stop without deleting datadocker rm kalamdb               # remove container; volume keeps datadocker rm -f kalamdb && docker volume rm kalamdb_data   # full reset

Notes

Last updated on
ConfigurationGitHub Binaries