Overview QIMEM provides official Docker images and Docker Compose configurations for both the encryption service (qimem-api) and the unified platform server (qauth-api).
Quick Start
Clone and prepare environment
Start with Docker Compose
docker compose up --build
Verify health
curl -fsS http://localhost:8080/health
Docker Compose Configuration Services The docker-compose.yml defines three services:
PostgreSQL Database postgres : image : postgres:16 environment : POSTGRES_USER : postgres POSTGRES_PASSWORD : postgres POSTGRES_DB : qimem ports : - "5432:5432" healthcheck : test : [ "CMD-SHELL" , "pg_isready -U postgres" ] interval : 5s timeout : 5s retries : 20
The PostgreSQL service is required when running QIMEM in stateful mode . The health check ensures the database is ready before dependent services start.
QIMEM API Service qimem-api : build : context : . dockerfile : Dockerfile depends_on : postgres : condition : service_healthy environment : QIMEM_MODE : stateful DATABASE_URL : postgres://postgres:postgres@postgres:5432/qimem?sslmode=disable QIMEM_BIND : 0.0.0.0:8080 RUST_LOG : info ports : - "8080:8080" healthcheck : test : [ "CMD" , "curl" , "-fsS" , "http://localhost:8080/health" ] interval : 10s timeout : 3s retries : 10
Port Mappings Service Container Port Host Port Purpose postgres5432 5432 PostgreSQL database qimem-api8080 8080 QIMEM encryption API qauth-api8080 8080 Unified platform API
Health Checks PostgreSQL Health Check
Interval : 5 secondsTimeout : 5 secondsRetries : 20 (100 seconds total)
QIMEM API Health Check curl -fsS http://localhost:8080/health
Interval : 10 secondsTimeout : 3 secondsRetries : 10 (100 seconds total)
Health response: Volume Configuration The default docker-compose.yml does not persist PostgreSQL data. For production use, add a volume mount: postgres : volumes : - postgres_data:/var/lib/postgresql/data volumes : postgres_data :
Dockerfile The multi-stage Dockerfile builds the qimem-api binary with the stateful feature:
FROM rust:1.82-slim AS builder WORKDIR /app COPY Cargo.toml Cargo.lock* ./ COPY src ./src COPY migrations ./migrations RUN cargo build --release --bin qimem-api --features stateful && strip target/release/qimem-api FROM debian:bookworm-slim RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates curl \ && rm -rf /var/lib/apt/lists/* RUN useradd -m -u 10001 qimem WORKDIR /app COPY --from=builder /app/target/release/qimem-api /usr/local/bin/qimem-api COPY migrations ./migrations USER qimem EXPOSE 8080 CMD [ "qimem-api" ]
Build Features
Builder stage : Uses rust:1.82-slim with --features statefulRuntime stage : Uses debian:bookworm-slim with minimal dependenciesSecurity : Runs as non-root user qimem (UID 10001)Optimizations : Binary is stripped to reduce image sizeDependencies : Includes ca-certificates and curl for health checks
Deployment Scenarios Stateful Mode (PostgreSQL)
Stateless Mode (In-Memory)
Custom Database URL
docker compose up -d postgres qimem-api curl http://localhost:8080/health
Running qauth-api vs qimem-api qimem-api (Encryption Only) Provides key management and encryption operations:
docker compose up qimem-api
Endpoints:
GET /healthPOST /keysPOST /encryptPOST /decryptPOST /rotate
Provides encryption + authentication + plugin management:
cargo build --release --bin qauth-api docker run -d \ -p 8080:8080 \ -e QIMEM_MODE=stateful \ -e DATABASE_URL=postgres://user:pass@host:5432/qimem \ qauth-api
Endpoints:
/v1/security/* - Encryption operations/v1/auth/* - Authentication (JWT, TOTP, RBAC)/v1/plugins/* - Plugin registration/health and /v1/security/health - Health checks
The qauth-api binary is not included in the default Dockerfile. Build it separately or modify the Dockerfile to include it.
Troubleshooting Service fails to start Check that PostgreSQL is healthy:
docker compose ps docker compose logs postgres
Connection refused errors Verify the DATABASE_URL uses the service name:
# Correct (inside Docker network) DATABASE_URL = postgres://postgres:postgres@postgres:5432/qimem # Incorrect (localhost won't work inside containers) DATABASE_URL = postgres://postgres:postgres@localhost:5432/qimem
Health check failures Increase health check timeouts:
healthcheck : interval : 15s timeout : 5s retries : 20
