Docker

Single-container quickstart

docker run -p 8000:8000 \
  -v /your/data:/data \
  -e HMDB_API_KEY=hmdb_yoursecretkey \
  hypermeshdb/server:latest

The server is available at http://localhost:8000.
Check liveness: curl http://localhost:8000/health/live

Docker Compose (recommended)

# docker-compose.yml (already in the repository root)
version: "3.9"
services:
  hypermeshdb:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - db_data:/data
      - backups:/backups
    environment:
      HMDB_API_KEY: "hmdb_changeme"
      HMDB_LOG_LEVEL: "INFO"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health/live"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  db_data:
  backups:

docker-compose up -d
docker-compose logs -f

Environment variables

Variable	Default	Description
HMDB_DIR	/data	Database directory
HMDB_API_KEY	—	Bootstrap API key (admin role). Required in production.
HMDB_AUTH_DISABLED	0	Set to 1 to disable auth (dev/testing only)
HMDB_LOG_LEVEL	INFO	Python log level (DEBUG, INFO, WARNING)
HMDB_AUDIT_LOG	—	Path to write JSON audit log lines
HMDB_RATE_LIMIT_QPM	1000	Requests per minute per API key
HMDB_TLS_CERT	—	Path to TLS certificate (enables HTTPS)
HMDB_TLS_KEY	—	Path to TLS private key

TLS (HTTPS)

Mount your certificates and set environment variables:

docker run -p 8443:8000 \
  -v /your/certs:/certs:ro \
  -v /your/data:/data \
  -e HMDB_API_KEY=hmdb_yoursecretkey \
  -e HMDB_TLS_CERT=/certs/server.crt \
  -e HMDB_TLS_KEY=/certs/server.key \
  hypermeshdb/server:latest

Or in docker-compose.yml:

environment:
  HMDB_TLS_CERT: /certs/server.crt
  HMDB_TLS_KEY:  /certs/server.key
volumes:
  - /your/certs:/certs:ro

Kubernetes

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hypermeshdb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hypermeshdb
  template:
    metadata:
      labels:
        app: hypermeshdb
    spec:
      containers:
        - name: hypermeshdb
          image: hypermeshdb/server:latest
          ports:
            - containerPort: 8000
          env:
            - name: HMDB_API_KEY
              valueFrom:
                secretKeyRef:
                  name: hypermeshdb-secret
                  key: api-key
            - name: HMDB_DIR
              value: /data
          volumeMounts:
            - name: data
              mountPath: /data
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8000
            initialDelaySeconds: 5
            periodSeconds: 10
          resources:
            requests:
              cpu:    "200m"
              memory: "256Mi"
            limits:
              cpu:    "2"
              memory: "2Gi"
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: hypermeshdb-pvc

Secret

kubectl create secret generic hypermeshdb-secret \
  --from-literal=api-key=hmdb_yourproductionkey

Prometheus metrics

HyperMesh DB exposes metrics at GET /metrics in Prometheus text format. Add a scrape target to your prometheus.yml:

scrape_configs:
  - job_name: hypermeshdb
    static_configs:
      - targets: ["hypermeshdb:8000"]
    bearer_token: hmdb_yourreadablekey