Deployment

This guide is for operators running the self-hosted Dakera server in production. It covers the supported ways to run v0.12.3 (Docker, Docker Compose, Kubernetes with Helm, and systemd), then what every deployment needs: TLS termination, the data volume, health probes, backups, monitoring, upgrades and rollback.

Every setting is an environment variable; the complete list is in the Configuration reference.

Docker (single node)

docker run -d \
  --name dakera \
  --restart unless-stopped \
  -p 3000:3000 \
  -e DAKERA_PORT=3000 \
  -e DAKERA_ROOT_API_KEY=your-secret \
  -e DAKERA_STORAGE=filesystem \
  -e DAKERA_STORAGE_PATH=/data \
  -v dakera-data:/data \
  -v dakera-models:/app/models \
  ghcr.io/dakera-ai/dakera:0.12.3

/data is the data root (write-ahead log, tiers, knowledge graph, filesystem storage): mount one volume there. /app/models holds only models the image does not ship, so you can leave it out with the default models. Authentication is on by default; send the key as Authorization: Bearer or X-API-Key. Add -p 50051:50051 for gRPC, which requires an API key.

The image ships its default models (bge-large and the bge-reranker-v2-m3 reranker) already converted, so a default start needs no network, downloads nothing and works with a read-only root filesystem. See Model store and air-gapped installs below.

Docker Compose (recommended)

The recommended way to run a single production node. This compose file runs Dakera on S3 storage provided by MinIO; a one-off minio-setup service creates the bucket, because the server checks at startup that the bucket exists and refuses to start without it.

# docker-compose.yml
services:
  dakera:
    image: ghcr.io/dakera-ai/dakera:0.12.3
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      DAKERA_PORT: 3000
      DAKERA_ROOT_API_KEY: ${DAKERA_ROOT_API_KEY}
      DAKERA_STORAGE: s3
      DAKERA_S3_ENDPOINT: http://minio:9000
      DAKERA_S3_BUCKET: dakera
      DAKERA_S3_REGION: us-east-1
      AWS_ACCESS_KEY_ID: ${MINIO_ROOT_USER}
      AWS_SECRET_ACCESS_KEY: ${MINIO_ROOT_PASSWORD}
      DAKERA_ENCRYPTION_KEY: ${DAKERA_ENCRYPTION_KEY}
      RUST_LOG: info
    volumes:
      - dakera-data:/data
    depends_on:
      minio-setup:
        condition: service_completed_successfully
    healthcheck:
      test: ["CMD", "dakera", "healthcheck", "/health/ready"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10m

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - minio-data:/data
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio-setup:
    image: minio/mc:latest
    depends_on:
      minio:
        condition: service_healthy
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    entrypoint: >
      /bin/sh -c "mc alias set local http://minio:9000 $$MINIO_ROOT_USER $$MINIO_ROOT_PASSWORD
      && mc mb --ignore-existing local/dakera"

volumes:
  dakera-data:
  minio-data:

# Generate secrets and start
printf "DAKERA_ROOT_API_KEY=%s\nDAKERA_ENCRYPTION_KEY=%s\nMINIO_ROOT_USER=minioadmin\nMINIO_ROOT_PASSWORD=%s\n" \
  "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 16)" > .env

docker compose up -d

Kubernetes

helm install dakera oci://ghcr.io/dakera-ai/dakera-helm/dakera \
  --version 0.12.3 --namespace dakera --create-namespace \
  --set dakera.rootApiKey="$(openssl rand -hex 32)" \
  --set minio.rootPassword="$(openssl rand -hex 16)"

Chart 0.12.3 deploys server 0.12.3 and Dashboard 0.5.2 (pin with --version 0.12.3). From 0.12.3 the server runs with a read-only root filesystem by default (dakera.readOnlyRootFilesystem) and only Dakera pods may reach the built-in MinIO (minio.networkPolicy). Settings without a dedicated value go through dakera.extraEnv; models can be pulled by an init container before the pod serves:

# values.yaml
dakera:
  extraEnv:
    - name: DAKERA_MODEL
      value: bge-m3
  models:
    pull: [configured]        # init container runs dakera models pull
    persistence:
      enabled: true           # keep the model cache across pods

Full values: charts/dakera/values.yaml · ArtifactHub. Kustomize manifests available in dakera-deploy/k8s/.

Reverse proxy & TLS termination

Nginx

# /etc/nginx/sites-available/dakera
server {
    listen 443 ssl http2;
    server_name dakera.example.com;

    ssl_certificate     /etc/letsencrypt/live/dakera.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/dakera.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # SSE support (required for event streaming)
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
    }
}

# Redirect HTTP → HTTPS
server {
    listen 80;
    server_name dakera.example.com;
    return 301 https://$host$request_uri;
}

# Obtain certificate with certbot
sudo certbot --nginx -d dakera.example.com

Caddy

# Caddyfile — automatic HTTPS with Let's Encrypt
dakera.example.com {
    reverse_proxy localhost:3000 {
        flush_interval -1   # required for SSE streaming
    }
}

Caddy automatically provisions and renews TLS certificates via Let's Encrypt — no additional setup required.

Self-hosted VPS

Run the Dakera binary directly on a Linux host (for example Ubuntu or Debian) under systemd. This suits a single node on dedicated hardware. With WorkingDirectory=/opt/dakera and no DAKERA_STORAGE_PATH, the data root is /opt/dakera/data.

# /etc/systemd/system/dakera.service
[Unit]
Description=Dakera Agent Memory Engine
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=dakera
Group=dakera
WorkingDirectory=/opt/dakera
ExecStart=/opt/dakera/dakera
Restart=always
RestartSec=5
LimitNOFILE=65535

# Environment
EnvironmentFile=/opt/dakera/.env

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable dakera
sudo systemctl start dakera

# Check status
sudo systemctl status dakera
curl http://localhost:3000/health

Cloud deployment

Resource sizing

Size from your own data and load: there is no published table by memory count. These are the figures measured for v0.12.0, with where they were taken.

Still being measured: the 50k capacity re-run, the embedder benchmark, the load sweep and durable writes per second. Media jobs reserve their working memory before they start and answer 503 with Retry-After when it does not fit. RocksDB (the tiered hot tier) benefits from high random-read IOPS; use SSD or NVMe. DAKERA_L1_CACHE_SIZE takes a vector count or a byte size such as 512MB.

Data root and volumes

Every local path derives from one data root, DAKERA_STORAGE_PATH (default ./data; the images set /data and declare it, with /app/models, as volumes). Before v0.12 the image's root was /app/data: a server that finds data there and none under /data keeps using it where it is and warns, naming the variable that pins it (data_location in /health config_warnings). Nothing is moved. Keep the whole data root on a persistent volume, also with S3 storage: it holds the knowledge graph and audit events.

DAKERA_ROCKSDB_PATH, DAKERA_CACHE_DIR, DAKERA_WAL_DIR, DAKERA_WAL_SNAPSHOT_DIR and DAKERA_GRAPH_PATH pin each path; DAKERA_DATA_DIR is an alias of DAKERA_STORAGE_PATH (two different values are an invalid value). Data at a pre-0.12 location is used where it is, with a warning.

• Tiered storage (DAKERA_TIERED_STORAGE, S3 as the cold tier): the hot tier is now RocksDB (DAKERA_HOT_TIER=rocksdb, the default) and its writes are fsynced (DAKERA_ROCKSDB_SYNC, default true), so a crash no longer loses acknowledged writes not yet in cold; DAKERA_HOT_TIER=memory keeps the old tier. Deletes are journaled and survive an S3 outage.
• S3: DAKERA_S3_TIMEOUT_SECS (default 30) bounds control requests and DAKERA_S3_IO_TIMEOUT_SECS (default 60) each data call. Cluster nodes must not share a bucket: each node writes a heartbeat marker, and another node's live marker refuses a fresh bucket (exit 78).
• Cluster: DAKERA_CLUSTER_SECRET is required on every node, fresh install or upgraded (v0.12.1; a node without it exits with code 78), and DAKERA_CLUSTER_NODE_ID on a fresh install. Set the secret on every node and upgrade them in one window (see High Availability).

Health checks

Since v0.12 the REST port is bound before models load, so a model that has to download no longer sits behind a closed port (a liveness probe used to restart the process, which downloaded again from zero). Use the two probe routes:

Every other request answers 503 with Retry-After: 5 until the models are loaded. The reranker, and whisper and the vision model when enabled, load in the background and do not gate readiness.

curl http://localhost:3000/health/ready
# {"ready":true,"version":"0.12.3","checks":{"storage":{"status":"ok","message":null},"embedding_engine":{...},"tiered_engine":{...}}}

Docker

The published images already carry a HEALTHCHECK with a 10-minute start period: dakera healthcheck, a probe built into the server binary (the images ship without curl from v0.12.3). It connects to the node's own REST port, requests the path you give it (default /health) and exits 0 only on 200. For your own compose file:

healthcheck:
  test: ["CMD", "dakera", "healthcheck", "/health/ready"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 10m

Kubernetes

# In pod spec — the startup probe covers port binding (write-ahead-log replay)
startupProbe:
  httpGet:
    path: /health/live
    port: 3000
  periodSeconds: 10
  failureThreshold: 60
livenessProbe:
  httpGet:
    path: /health/live
    port: 3000
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  periodSeconds: 10

The Helm chart (dakera-helm) is already set up this way (liveness on /health/live behind a 10-minute startup probe, readiness on /health/ready) and sets a pod security context of uid/gid 1000 with fsGroup: 1000.

Model store and air-gapped installs

Models other than the shipped defaults (another embedding model such as bge-m3, whisper, the vision model, GLiNER entity extraction) download on first use into the model cache, HF_HOME (/app/models in the images, a VOLUME). Mount a volume there to download each model once. Every file is checked against a pinned SHA-256. Downloads honour HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXY, HF_ENDPOINT (a mirror) and HF_HUB_OFFLINE.

# What is on disk, and what can go
docker exec dakera dakera models list
docker exec dakera dakera models prune --dry-run

# Fetch a model ahead of the first start
docker run --rm -v dakera-models:/app/models ghcr.io/dakera-ai/dakera:0.12.3 models pull bge-m3

# Air-gapped: seed on a connected machine, copy to the host, mount at /app/models
docker run --rm -v "$PWD/models:/seed" ghcr.io/dakera-ai/dakera:0.12.3 models pull --dir /seed bge-m3 whisper vision
# ...then run with -v ./models:/app/models -e HF_HUB_OFFLINE=1

Backup & restore

Dakera provides backup and restore through the admin API. A backup holds the namespaces' records with their sidecars, attachments and knowledge-graph edges, the API-key records and the encryption keyring; text is kept sealed (a backup never holds plaintext _text). Creating, listing and polling need global admin; download, upload and restore need global super_admin.

# Create a backup (202; the backup runs in the background)
curl -X POST http://localhost:3000/admin/backups \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"before-upgrade","compression":"zstd","encrypt":false}'
# {"backup":{"backup_id":"...","name":"before-upgrade","status":"...", ...}}

# Poll it, or list all
curl http://localhost:3000/admin/backups/BACKUP_ID -H "Authorization: Bearer $DAKERA_ROOT_API_KEY"
curl http://localhost:3000/admin/backups -H "Authorization: Bearer $DAKERA_ROOT_API_KEY"

# Download a completed backup (a gzip-compressed JSON bundle)
curl -o backup.json.gz \
  http://localhost:3000/admin/backups/BACKUP_ID/download \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY"

# Restore a stored backup (202 with a restore_id; add "overwrite": true for the exact point in time)
curl -X POST http://localhost:3000/admin/backups/restore \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backup_id":"BACKUP_ID","overwrite":false}'

# Restore from a downloaded bundle (raw gzip body; needs S3 storage)
curl -X POST http://localhost:3000/admin/backups/upload \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  --data-binary @backup.json.gz

• compression is none or zstd; lz4 is a 400. encrypt: true seals each file with AES-256-GCM under a key derived from DAKERA_ENCRYPTION_KEY and is a 400 without that key. Both are recorded in the backup's manifest, which also carries the taking node's node_id. incremental is reported as full.
• Without overwrite a restore is the v0.11 merge (the backup's records are written over the current copies, later records kept); with "overwrite": true it is the backup's point in time. Revoked API keys stay revoked, and the keyring only gains keys it lacks. One restore runs at a time (409), and serving is not paused: restore in a maintenance window. With one bucket per node, a restore or download on a node that does not hold the backup's files is 409 naming the owning node.
• A backup that a stop interrupted is marked failed at the next start.

Scheduled backups

# Daily at 02:00, 30-day retention, zstd
curl -X POST http://localhost:3000/admin/backups/schedule \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"cron":"0 2 * * *","retention_days":30,"max_backups":30,"compression":"zstd"}'

Since v0.12 a stored, enabled schedule runs: one backup per due slot, on the leader in a cluster; retention_days and max_backups apply to scheduled backups only. An upgraded deployment with an enabled stored schedule gets a backup_schedule configuration warning at its first start.

Monitoring & observability

Dakera exposes Prometheus metrics at GET /metrics (no key; scrape it from inside your network and do not expose it publicly). GET /v1/ops/metrics returns the same exposition behind a key with global admin scope. The names below are emitted by the v0.12.0 server.

Prometheus scrape config

# prometheus.yml
scrape_configs:
  - job_name: dakera
    scrape_interval: 15s
    static_configs:
      - targets: ["dakera:3000"]
    metrics_path: /metrics

Alert recommendations

OpenTelemetry tracing

# Enable OTLP trace export
DAKERA_TRACING_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
OTEL_SERVICE_NAME=dakera

Telemetry

The self-hosted engine sends product telemetry to Dakera's PostHog project (EU) to show which versions, platforms and storage setups are in use, whether engines stay up and how often they are upgraded. It never reads or sends memory content, embeddings, queries, ids, names, API keys, file paths or URLs.

Opt out

# Either variable turns telemetry off completely — nothing is counted, written or sent
DAKERA_TELEMETRY=0
DO_NOT_TRACK=1

Log management

Dakera writes its logs to standard output; RUST_LOG sets the filter (the images set info). Audit records are one line per request, JSON by default (DAKERA_AUDIT_FORMAT).

# Log levels
RUST_LOG=info                          # production (recommended)
RUST_LOG=debug                         # development / troubleshooting
RUST_LOG=info,tower_http=debug         # verbose HTTP logging only

Log retention

Rotate logs where they are collected. Under systemd they go to the journal (journalctl -u dakera; retention is set in journald.conf). Under Docker, set the logging driver's rotation:

# docker-compose.yml, on the dakera service
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "5"

Upgrading

v0.12.3 upgrades in place from v0.11.108, v0.12.0, v0.12.1 or v0.12.2 on the same data and environment, and goes back to v0.11.108 with one command (dakera downgrade). Read Upgrading to v0.12 before you start — it lists what changes on purpose. In short:

1. Take a backup: POST /admin/backups.
2. Run the new image's dakera --check-config against the deployment's environment and data volume; fix or note each warning.
3. Give gRPC clients an API key; check namespace-pinned keys and backup tooling against the new permissions (from v0.11.108).
4. Cluster: set the same DAKERA_CLUSTER_SECRET on every node and upgrade the nodes in one window (see High Availability).
5. Sessions: from v0.12.2 the server ends sessions idle for 4 hours (DAKERA_SESSION_IDLE_TIMEOUT_SECS; 0 keeps them open until a client ends them). Check clients that write reserved metadata keys or over-size content against the v0.12.2 checks.
6. Health checks and admin tooling: from v0.12.3 probe with dakera healthcheck instead of curl inside the container, give tooling that calls POST /ops/shutdown a super_admin key, and set DAKERA_AUTOPILOT_DEDUP_MODE=merge if you rely on automatic deduplication (v0.12.3 checks).
7. Stop the running version and start v0.12.3 on the same data and environment.
8. Nothing to do for the full-text indexes: v0.12.3 re-analyses indexes built by v0.11.108 in the background while they serve. (On v0.12.0 this was a manual step; see Full-text indexes.)
9. Watch /health: config_warnings, degraded, embed_migration.

# 1. Pull the new image
docker pull ghcr.io/dakera-ai/dakera:0.12.3

# 2. Restart the container on the same volumes and environment
docker compose down && docker compose up -d

# 3. Wait for readiness and verify the version
curl http://localhost:3000/health/ready
# {"ready":true,"version":"0.12.3","checks":{...}}
curl http://localhost:3000/health
# {"service":"dakera","status":"healthy","version":"0.12.3","degraded":[],"config_warnings":[], ...}

For systemd deployments: replace the binary at /opt/dakera/dakera, then sudo systemctl restart dakera. Always verify the readiness endpoint after upgrade. Clusters that already run v0.12.0, v0.12.1 or v0.12.2 with DAKERA_CLUSTER_SECRET upgrade node by node; otherwise set the secret and switch every node in one window (see High Availability). After an upgrade from v0.11.108, stored memories that need it are re-embedded once in the background (about 35 minutes per 10,000 memories on bge-large; nothing to do for minilm, gte-modernbert-base, bge-m3 or colbert-small); recall is served throughout.

Rolling back

Stop v0.12, run dakera downgrade once with the server's environment and volumes (docker run --rm <env and volumes> ghcr.io/dakera-ai/dakera:0.12.3 downgrade), read its JSON report (exit 0: the data is v0.11.108's; 1: run it again; 78: it refused and changed nothing), then start v0.11.108 (from v0.12.2 the downgrade also rewrites binary RocksDB hot-tier records as JSON). Going back to v0.12.2, v0.12.1 or v0.12.0 needs no downgrade. Details and what blocks a rollback: Rolling back to v0.11.

Production checklist

Environment variable reference

The most-used variables, grouped by category. Every variable, with the values it accepts, is in the Configuration reference.

Core

Storage

Security

Audit & tracing

Clustering

Inference & retrieval

AutoPilot & decay

Related: Dakera Dashboard (admin UI) · Security hardening · High availability & clustering · Architecture · Full configuration reference · Self-hosted deployment walkthrough