aarkam/aarkam.kdouja repository overview

⁠1. What is Kdouja?

Aarkam Kdouja is the high-performance autonomous storage engine of the Aarkam Sovereign Data Fabric. Operating directly on bare-metal NVMe drives and containerized enterprise substrates, Kdouja delivers sub-millisecond point lookups, zero-allocation LSM memory structures, hardware-level Direct I/O block allocation, and native AES-256 Write-Ahead Log (WAL) durability across sovereign cloud environments.

Kdouja serves as the foundational storage substrate for:

1. Aarkam Rokka: Powers local object catalog indexing, bucket metadata tables, and high-frequency SSTable deduplication.
2. Aarkam Abodi: Powers unbuffered 66,048-byte physical block allocations, Cauchy shard placement, and direct NVMe queue saturation.
3. Autonomous Edge Nodes: Operates as a zero-dependency, self-contained embedded storage engine or network daemon (kdoujad) with dedicated inspection tooling (kdouja-cli).

Engineered strictly for zero-egress, air-gapped sovereign datacenters, Kdouja operates with complete autonomy—requiring zero external database dependencies (no Redis, no ZooKeeper), zero third-party internet callbacks, and zero native C++ redistributable packages.

⁠2. Quick Start

⁠Pull the Image

docker pull aarkam/aarkam.kdouja:latest
# or explicit version
docker pull aarkam/aarkam.kdouja:v1.0.1

⁠3. Usage Modes

⁠Mode A: Autonomous Storage Daemon (kdoujad)

Run Kdouja as an autonomous background daemon exposing high-throughput gRPC services (KeyValueService and StorageService) on port 57771:

docker run -d \
  --name kdouja-server \
  -p 57771:57771 \
  -v kdouja_data:/var/lib/kdouja \
  -e KDOUJA_BASE_DIRECTORY="/var/lib/kdouja" \
  -e KDOUJA_MEMTABLE_FLUSH_MB="32" \
  -e KDOUJA_ENABLE_DIRECT_IO="false" \
  aarkam/aarkam.kdouja:v1.0.1

Check server health:

curl http://localhost:57771/healthz

⁠Mode B: Enterprise CLI & Inspector (kdouja-cli)

Use the bundled kdouja-cli tool to query keys, inspect SSTables, view WAF/RAF metrics, and trigger compactions:

# Display engine diagnostics in structured JSON
docker run --rm \
  -v kdouja_data:/var/lib/kdouja \
  aarkam/aarkam.kdouja kdouja-cli info --dir /var/lib/kdouja --json

# Store a key-value record
docker run --rm \
  -v kdouja_data:/var/lib/kdouja \
  aarkam/aarkam.kdouja kdouja-cli kv put "config:mode" "sovereign" --dir /var/lib/kdouja --json

# Read a record in table format
docker run --rm \
  -v kdouja_data:/var/lib/kdouja \
  aarkam/aarkam.kdouja kdouja-cli kv get "config:mode" --dir /var/lib/kdouja --table

# Trigger manual SSTable compaction pass
docker run --rm \
  -v kdouja_data:/var/lib/kdouja \
  aarkam/aarkam.kdouja kdouja-cli compact --dir /var/lib/kdouja --json

⁠4. Why Kdouja Wins Against Competitors

⁠5. Environment Variables

⁠6. Persistent Volumes

⁠7. Docker Compose Example

version: '3.8'

services:
  kdouja:
    image: aarkam/aarkam.kdouja:v1.0.1
    container_name: aarkam-kdouja
    restart: unless-stopped
    ports:
      - "57771:57771"
    environment:
      - KDOUJA_BASE_DIRECTORY=/var/lib/kdouja
      - KDOUJA_MEMTABLE_FLUSH_MB=64
      - KDOUJA_ENABLE_WAL_FSYNC=true
      - KDOUJA_ENABLE_DIRECT_IO=false
    volumes:
      - ./kdouja_data:/var/lib/kdouja
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:57771/healthz"]
      interval: 10s
      timeout: 3s
      retries: 3

⁠8. Security & Sovereign Compliance

• Saudi NCA ECC-2:2024 & FIPS 140-3: Cryptographic isolation, authenticated memory bounds, and native AES-256 WAL encryption at rest.
• 100% Air-Gapped: Runs entirely offline in disconnected data centers.
• Zero Kernel Thrashing: Sector-aligned Direct I/O eliminates dirty-page memory leaks on long-running nodes.
• Documentation: https://github.com/aarkamio/Aarkam.Kdouja⁠