Skip to content

README.md

Latest commit

 

History

History
382 lines (270 loc) · 10.2 KB

README.md

File metadata and controls

382 lines (270 loc) · 10.2 KB

KalamDB Docker Guide

KalamDB is a SQL-first realtime backend for agent-native apps. Agents and frontends share one HTTP SQL API for reads and writes plus WebSocket live subscriptions, with USER tables and auth keeping access policy-scoped. This directory contains the Docker image definitions and compose setups used to run KalamDB as a single node or a 3-node cluster.

The Docker image ships with both binaries:

  • kalamdb-server for the database server
  • kalam and kalam-cli for the command-line client

What Is Here

docker/
├── build/
│   ├── Dockerfile             # Full source build image
│   ├── Dockerfile.prebuilt    # Runtime image from prebuilt binaries
│   ├── build-and-test-local.sh
│   └── test-docker-image.sh
└── run/
    ├── single/
    │   ├── docker-compose.yml
    │   └── server.toml
    └── cluster/
        ├── docker-compose.yml
        ├── server1.toml
        ├── server2.toml
        └── server3.toml

docker/utils/
├── docker-compose.yml         # Local utility services (Dex, MinIO, Jaeger)
├── .env.example               # Optional Google connector values for Dex
└── dex/config.yaml            # Shared Dex dev config with static clients, users, and Google connector

Quick Start

Pull and run the published image

docker pull jamals86/kalamdb:latest

docker run -d \
  --name kalamdb \
  -p 2900:2900 \
  -e KALAMDB_SERVER_HOST=0.0.0.0 \
  -e KALAMDB_ROOT_PASSWORD=kalamdb123 \
  -e KALAMDB_JWT_SECRET="replace-with-a-32-char-secret" \
  -v kalamdb_data:/data \
  jamals86/kalamdb:latest

Verify the server is healthy:

curl http://localhost:2900/health
curl http://localhost:2900/v1/api/healthcheck

Run with Docker Compose

The single-node compose file maps container port 2900 to host port 2900 by default.

cd docker/run/single
export KALAMDB_JWT_SECRET="replace-with-a-32-char-secret"
docker compose up -d

Open the server at http://localhost:8088.

To change the host port:

KALAMDB_PORT=2900 docker compose up -d

Start a 3-node cluster

cd docker/run/cluster
export KALAMDB_JWT_SECRET="replace-with-a-32-char-secret"
docker compose up -d

Default node endpoints:

  • Node 1: http://localhost:2901
  • Node 2: http://localhost:2902
  • Node 3: http://localhost:2903

Build the Image Locally

Recommended: build from prebuilt binaries

This is the path used by the release workflow. Build the Rust binaries once, then create the smaller runtime image.

./docker/build/build-and-test-local.sh kalamdb:local

That script will:

  1. Build Linux-targeted kalamdb-server and kalam binaries for your local Docker platform
  2. Stage them as a Docker build context
  3. Build docker/build/Dockerfile.prebuilt
  4. Run smoke tests against the resulting image

Manual prebuilt image build

cd /path/to/KalamDB

case "$(uname -m)" in
  x86_64)
    export LOCAL_TARGET=x86_64-unknown-linux-gnu
    export LOCAL_PLATFORM=linux/amd64
    export BIN_DIR=binaries-amd64
    SKIP_UI_BUILD=1 cargo build --release --target "$LOCAL_TARGET" --features mimalloc -p kalamdb-server -p kalam-cli --bin kalamdb-server --bin kalam
    ;;
  arm64)
    export LOCAL_TARGET=aarch64-unknown-linux-gnu
    export LOCAL_PLATFORM=linux/arm64
    export BIN_DIR=binaries-arm64
    SKIP_UI_BUILD=1 cross build --release --target "$LOCAL_TARGET" --features mimalloc -p kalamdb-server -p kalam-cli --bin kalamdb-server --bin kalam
    ;;
esac

mkdir -p "$BIN_DIR"
cp "target/$LOCAL_TARGET/release/kalamdb-server" "$BIN_DIR/"
cp "target/$LOCAL_TARGET/release/kalam" "$BIN_DIR/"

docker build \
  --platform "$LOCAL_PLATFORM" \
  --build-context binaries="$BIN_DIR" \
  -f docker/build/Dockerfile.prebuilt \
  -t kalamdb:local \
  .

Full source build inside Docker

For maintainers, docker/build/Dockerfile performs a full multi-stage source build and then packages the server and CLI into a runtime image.

docker build -f docker/build/Dockerfile -t kalamdb:source-build .

Authentication and First Login

If you set KALAMDB_ROOT_PASSWORD, you can authenticate immediately after startup.

curl -X POST http://localhost:2900/v1/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"root","password":"kalamdb123"}'

Then run a SQL request with the returned bearer token:

curl -X POST http://localhost:2900/v1/api/sql \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT 1 AS ok"}'

Using the CLI in the Container

The image includes the Kalam CLI under both kalam and kalam-cli.

Inside the container, the CLI stores local config, credentials, and history in /data/.kalam by default so they persist with the /data volume.

docker exec -it kalamdb kalam --version
docker exec -it kalamdb kalam-cli --version

If you want an interactive shell in the container, use bash:

docker exec -it kalamdb bash

Configuration

The container starts with:

  • data under /data
  • config under /config/server.toml
  • JSON file logging enabled in Docker configs so system.server_logs can return rows
  • server command kalamdb-server /config/server.toml

The single-node compose file already mounts a persistent volume for /data. To provide your own config, mount a custom server.toml over /config/server.toml.

Example:

services:
  kalamdb:
    volumes:
      - kalamdb_data:/data
      - ./server.toml:/config/server.toml:ro

Important environment variables used by the compose files:

  • KALAMDB_JWT_SECRET: required for safe non-localhost deployments
  • KALAMDB_ROOT_PASSWORD: optional root password for immediate login
  • KALAMDB_PORT: host port override for the single-node compose setup
  • KALAMDB_LOG_LEVEL: server log level

Local Auth Utilities

The utility compose stack under docker/utils now includes Dex on http://127.0.0.1:5556 using the checked-in config at docker/utils/dex/config.yaml.

Start Dex only:

cd docker/utils
docker compose up -d dex

The shared dev client matches the KalamDB OIDC examples:

  • public client id: client
  • no client secret for Admin UI or CLI browser PKCE login
  • Admin UI callbacks for http://127.0.0.1:2900/ui/oauth/callback, http://127.0.0.1:4175/ui/oauth/callback, and localhost equivalents
  • CLI browser callback http://127.0.0.1:8787/callback
  • device-flow completion callback /device/callback
  • example user password: kalamdb123

The Dex config seeds 10 example users: alice, bob, carol, dave, erin, frank, grace, heidi, ivan, and judy with @example.org email addresses.

To test Google sign-in through Dex, create a Google OAuth client and add this authorized redirect URI:

http://127.0.0.1:5556/callback

Then copy the local env template and fill in the Google OAuth client values:

cd docker/utils
cp .env.example .env
$EDITOR .env
docker compose up -d dex

The .env file is intentionally ignored by Git. Compose reads it from the same directory as docker-compose.yml and exports GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI into the Dex container. Dex then reads those values from docker/utils/dex/config.yaml through the Google connector's $GOOGLE_* settings.

Dex local static userID values are OIDC sub claims and KalamDB uses that same subject as the final user_id. For the default local Dex Alice user, the KalamDB user id is dev-alice.

If you sign in through Google, the subject is Google's stable account id as emitted by Dex. If you change the Dex userID values or switch to another issuer/provider that emits different subjects, KalamDB treats those subjects as different users.

Persistence

The default compose setup stores data in Docker-managed volumes.

Inspect the single-node volume:

docker volume inspect kalamdb_data

Back up the data volume:

docker run --rm \
  -v kalamdb_data:/data \
  -v "$PWD":/backup \
  alpine \
  tar czf /backup/kalamdb-data.tar.gz /data

Smoke Testing

To validate an image locally:

./docker/build/test-docker-image.sh kalamdb:local

The smoke test checks:

  • server startup and health endpoints
  • presence of kalamdb-server, kalam-cli, and kalam
  • root login flow
  • SQL execution through the HTTP API

Troubleshooting

Container starts but is unreachable

Make sure the server is bound to 0.0.0.0 when publishing ports from Docker.

docker logs kalamdb

Compose stack is healthy but login fails

If you did not set KALAMDB_ROOT_PASSWORD, set one explicitly and recreate the container.

Port collision on the host

Override the published port:

KALAMDB_PORT=8090 docker compose up -d

Clean reset

docker compose down -v
docker volume prune

Use volume deletion carefully. It removes persisted KalamDB data.

Related Links

  • Main project README: ../README.md
  • Docker single-node compose: run/single/docker-compose.yml
  • Docker cluster compose: run/cluster/docker-compose.yml
  • Project docs: https://kalamdb.org/docs

Create new user

docker exec kalamdb kalam-cli user create --name "newuser" --role "user"


---

## Advanced Configuration

### Custom Dockerfile

If you need to modify the build:

1. Copy `Dockerfile` to `Dockerfile.custom`
2. Make your changes
3. Build: `docker build -f Dockerfile.custom -t kalamdb:custom ../../`

### Debug Mode

Run with debug logging:

```bash
docker-compose up -d
docker-compose exec kalamdb kalam-cli exec "UPDATE system.config SET log_level='debug'"
docker-compose restart

Health Check Customization

Edit docker-compose.yml:

healthcheck:
  test: ["CMD", "/usr/local/bin/kalam-cli", "exec", "SELECT COUNT(*) FROM system.users"]
  interval: 10s
  timeout: 5s
  start_period: 30s
  retries: 5

Related Documentation

Support

For issues and questions: