Skip to content

REPO-README.md

Latest commit

 

History

History
277 lines (196 loc) · 7.14 KB

REPO-README.md

File metadata and controls

277 lines (196 loc) · 7.14 KB

🚀 KalamDB on Docker Hub

KalamDB is a SQL-first realtime backend for agent-native apps. Give AI agents one SQL tool to your app data, while your frontend subscribes to live rows from the same backend.

It combines in one runtime:

  • ⚡ One SQL API for reads and writes
  • 🔄 Live subscriptions over WebSocket
  • 📡 Pub/sub streams
  • 🔐 Built-in auth with JWT support
  • 🧱 Per-user isolation with policy-scoped access
  • 💾 Hot storage on RocksDB
  • 📦 Cold storage on Parquet
  • 🛠️ Included CLI tools in the image

The Docker image includes:

  • kalamdb-server
  • kalam
  • kalam-cli

✨ Quick Start

🐳 Pull and run

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

✅ Check health

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

🔑 Login

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

🧪 Run your first SQL query

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

🧩 Docker Compose

📄 Single-node compose file

🧱 3-node cluster compose file

⚡ Start single node with compose

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

By default, the single-node compose file publishes KalamDB on http://localhost:8088.

⚡ Start 3-node cluster with compose

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

Cluster endpoints:

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

🌐 One-line startup from the repo

Single node:

KALAMDB_JWT_SECRET=replace-with-a-32-char-secret \
curl -sSL https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/single/docker-compose.yml | docker compose -f - up -d

3-node cluster:

KALAMDB_JWT_SECRET=replace-with-a-32-char-secret \
curl -sSL https://raw.githubusercontent.com/kalamdb/KalamDB/main/docker/run/cluster/docker-compose.yml | docker compose -f - up -d

🖥️ Open the UI

If the Admin UI is enabled in your image and config, open:

  • Single container run: http://localhost:2900
  • Single-node compose: http://localhost:8088
  • Cluster node 1: http://localhost:2901

Useful API endpoints:

  • Health: GET /health
  • Extended health: GET /v1/api/healthcheck
  • Login: POST /v1/api/auth/login
  • SQL API: POST /v1/api/sql

🛠️ CLI Commands

The image includes both kalam and kalam-cli.

📌 Basic CLI usage

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

🐚 Open a shell inside the container

The image includes bash for direct shell access:

docker exec -it kalamdb bash

▶️ Useful commands to run inside the container

docker exec -it kalamdb kalam --help
docker exec -it kalamdb kalam-cli --help
docker exec -it kalamdb /usr/local/bin/kalamdb-server --help

📋 Common Docker commands

# View logs
docker logs -f kalamdb

# Stop container
docker stop kalamdb

# Start container
docker start kalamdb

# Remove container
docker rm -f kalamdb

# List volumes
docker volume ls

# Inspect persisted data volume
docker volume inspect kalamdb_data

🌱 Environment Variables

These are the most useful environment variables for setup and day-to-day use.

Variable Purpose Example
KALAMDB_SERVER_HOST Bind address inside the container 0.0.0.0
KALAMDB_ROOT_PASSWORD Root user password for initial login kalamdb123
KALAMDB_JWT_SECRET JWT signing secret, should be at least 32 chars super-secret-value
KALAMDB_LOG_LEVEL Logging level info
KALAMDB_PORT Host port override in single-node compose 2900
KALAMDB_ALLOW_REMOTE_SETUP Allow initial remote setup in Docker-based development flows true
KALAMDB_CLUSTER_ID Cluster identifier for multi-node deployments docker-cluster
KALAMDB_NODE_ID Node id in cluster setups 1
KALAMDB_CLUSTER_RPC_ADDR Raft RPC address for a node kalamdb-node1:2910
KALAMDB_CLUSTER_API_ADDR Public API address for a node http://kalamdb-node1:2900
KALAMDB_CLUSTER_PEERS Cluster peer list for Docker cluster compose 2@node2:2910@http://node2:2900;3@node3:2910@http://node3:2900

🔐 Security note

For anything beyond local testing:

  • change KALAMDB_ROOT_PASSWORD
  • use a strong KALAMDB_JWT_SECRET
  • persist /data with a Docker volume or bind mount

💾 Persistence

KalamDB stores database state under /data inside the container.

Run with a named volume:

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

Backup example:

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

🔍 Troubleshooting

Container is up but you cannot connect

docker logs kalamdb

Make sure:

  • port 2900 is published
  • KALAMDB_SERVER_HOST=0.0.0.0
  • your JWT secret is set when binding beyond localhost

Login is failing

Make sure the password you use matches KALAMDB_ROOT_PASSWORD from container startup.

You see Permission denied (os error 13) on startup

The image runs as a non-root user.

The bundled CLI uses /data/.kalam as its default local state directory inside the container.

Check these first:

  • if you mounted a custom server.toml, make sure the file is readable inside the container
  • if your custom config changes logs_path or data_path, make sure those paths are writable
  • if you bind-mount a host directory to /data or /config, make sure Docker grants the container write access
  • for the simplest persistent setup, prefer a named Docker volume for /data

You want a clean reset

docker rm -f kalamdb
docker volume rm kalamdb_data

🔗 Links