Deployment

Deployment guidance for Arqen applications.

Deployment modes

Memory mode (development)

No external dependencies. Suitable for local development and CI.

arqen dev --storage memory

• In-memory thingd engine
• Process-local and disposable
• No persistence across restarts

Native durable thingd

Use the native storage mode for local durable storage without a separate thingd service.

[storage]
mode = "native"
persistent_path = "/var/lib/arqen/data"

ARQEN_STORAGE_MODE=native ARQEN_PERSISTENT_PATH=/var/lib/arqen/data arqen start

HTTP sidecar

Connect to an external thingd service over HTTP:

[storage]
mode = "http"
http_url = "http://thingd:8080"

ARQEN_STORAGE_MODE=http ARQEN_THINGD_URL=http://thingd:8080 arqen start

Cloud (future)

Cloud integration is optional. A hosted thingd-cloud adapter must use a documented public customer API, not control-plane databases or private modules.

Before using cloud storage for a multi-user application, validate the application-hardening requirements: production configuration guardrails, tenant/instance identity, scoped repositories, HTTP contract tests, request idempotency, conditional writes, backups, and a separate worker role. See application-hardening.md.

Docker deployment

Build a release binary and containerize it:

FROM rust:1.96 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features cli

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/arqen /usr/local/bin/
EXPOSE 8888
CMD ["arqen", "start"]

Build and run:

docker build -t my-arqen-app .
docker run -p 8888:8888 \
  -e ARQEN_STORAGE_MODE=http \
  -e ARQEN_THINGD_URL=http://thingd:8080 \
  my-arqen-app

Environment variables for production

Variable	Recommended value
ARQEN_HOST	0.0.0.0
ARQEN_PORT	8888
ARQEN_STORAGE_MODE	http or native
ARQEN_THINGD_URL	thingd service URL
ARQEN_THINGD_AUTH_TOKEN	server-side thingd token
ARQEN_LOG_LEVEL	warn or info
ARQEN_LOG_FORMAT	json
ARQEN_JWT_SECRET	secret value

Health and readiness

Orchestrators use health endpoints for lifecycle decisions:

• GET /health - liveness probe (restart the process if failing)
• GET /ready - readiness probe (stop routing traffic if failing)

Kubernetes example:

livenessProbe:
  httpGet:
    path: /health
    port: 8888
  initialDelaySeconds: 5
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /ready
    port: 8888
  initialDelaySeconds: 3
  periodSeconds: 5

Checklist

Every deployment should address:

• Release builds (cargo build --release)
• Environment variables documented above
• Secret management (env vars or secrets manager, never committed)
• Health and readiness checks
• Graceful shutdown (ARQEN_SHUTDOWN_TIMEOUT)
• Worker scaling (ARQEN_WORKER_CONCURRENCY)
• thingd connectivity and credentials
• Structured log collection (JSON format)
• Production configuration validation (AppConfig::validate_production())
• Durable storage and backup ownership
• Tenant/instance routing and isolation tests
• Conditional-write and idempotency behavior
• Cloud API contract/version compatibility
• Queue lag, dead-letter, and worker health monitoring