Quickstart & Deployment Guide

This guide walks you through provisioning a local Aarkam developer instance using Docker Compose, followed by production sizing recommendations for enterprise clusters.

1. Prerequisites

Before deploying Aarkam, verify that your host meets the minimum system requirements:

• OS: Enterprise Linux (RHEL 9, Rocky Linux 9, Ubuntu 22.04 LTS) or Windows Server 2022+
• CPU Architecture: x86_64 with AVX2 or AVX-512 support (Intel Xeon Scalable 3rd/4th Gen or AMD EPYC Genoa)
• Memory: Minimum 16 GB RAM (64 GB+ recommended for production per storage node)
• Container Runtime: Docker Engine 24.0+ and Docker Compose v2.20+

grep -E "(avx2|avx512f)" /proc/cpuinfo

2. Launching Developer Sandbox via Docker Compose

Create a docker-compose.yml configuration:

version: '3.8'

services:
  aarkam-gateway:
    image: aarkam/gateway:beta
    container_name: aarkam-gateway
    ports:
      - "57776:57776" # S3 REST Endpoint
      - "57775:57775" # Web Management Portal
    environment:
      - AARKAM_ENV=Development
      - S3_ACCESS_KEY=AKIASOVEREIGNKEY2026
      - S3_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      - CLUSTER_COORDINATOR_URL=http://aarkam-coordinator:57777
    depends_on:
      - aarkam-coordinator

  aarkam-coordinator:
    image: aarkam/coordinator:beta
    container_name: aarkam-coordinator
    ports:
      - "57777:57777"
    environment:
      - RAFT_CLUSTER_ID=aarkam-cluster-alpha
      - RAFT_PEERS=http://aarkam-coordinator:57777
      - ERASURE_PROFILE=8+3

  aarkam-node-1:
    image: aarkam/storage-node:beta
    volumes:
      - /mnt/nvme0/aarkam-data:/var/lib/aarkam/kdouja
    environment:
      - NODE_ID=node-1
      - DIRECT_IO_ENABLED=true
      - COORDINATOR_ENDPOINT=http://aarkam-coordinator:57777

  aarkam-abodi:
    image: aarkam/abodi-sidecar:beta
    privileged: true
    volumes:
      - /dev:/dev:ro
      - /sys:/sys:ro
    environment:
      - MONITOR_DISKS=/dev/nvme0n1
      - METRICS_PUSH_INTERVAL=5s

Run the cluster in daemon mode:

docker compose up -d

3. Verifying S3 API Compatibility

Once initialized, test S3 upload and download operations using standard AWS CLI or MinIO Client (mc):

# Configure standard S3 credentials
aws configure set aws_access_key_id AKIASOVEREIGNKEY2026
aws configure set aws_secret_access_key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws configure set default.region ksa-central-1

# Create sovereign bucket
aws s3 mb s3://sovereign-vault --endpoint-url http://localhost:57776

# Upload a file with automated client-side AES-256-GCM envelope encryption
aws s3 cp enterprise-backup.tar.gz s3://sovereign-vault/ --endpoint-url http://localhost:57776

# List bucket contents
aws s3 ls s3://sovereign-vault/ --endpoint-url http://localhost:57776