Installation

Installation Methods

Choose the installation method that fits your environment:

Docker (Recommended)

Quick setup with all dependencies included

Build from Source

Direct binary execution with cargo

Docker Installation

Docker Compose provides the fastest path to a working QIMEM deployment with Postgres persistence.

Clone the repository

git clone <repository-url>
cd qimem

Configure environment variables

cp .env.example .env

Edit .env with your configuration:

.env

QIMEM_MODE=stateful
DATABASE_URL=postgres://postgres:postgres@postgres:5432/qimem
QIMEM_BIND=0.0.0.0:8080
RUST_LOG=info

For stateless mode (in-memory storage), set QIMEM_MODE=stateless and omit DATABASE_URL.

Launch with Docker Compose

docker compose up --build

This command:

Builds the Rust binaries with release optimizations
Starts PostgreSQL 16 with health checks
Runs qimem-api in stateful mode on port 8080
Applies database migrations automatically

The first build may take 5-10 minutes to compile dependencies.

Verify the deployment

curl -fsS http://localhost:8080/health

Expected response:

{"status":"ok"}

Check the ready endpoint:

curl -fsS http://localhost:8080/ready

Expected response:

{"status":"ready"}

Docker Compose Services

The docker-compose.yml defines three services:

postgres

Image: postgres:16
Port: 5432
Database: qimem
Health check: pg_isready every 5 seconds
Environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=qimem

qimem-api

Build: Multi-stage Dockerfile with Rust 1.82
Port: 8080
Mode: Stateful with Postgres backend
Features: --features stateful
Health check: curl http://localhost:8080/health every 10 seconds
Dependencies: Waits for postgres to be healthy

devcontainer

Purpose: Development environment with Rust toolchain
Usage: Supports VS Code Remote Containers
Command: sleep infinity (keeps container running)

Build from Source

For development or environments without Docker:

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

Verify installation:

rustc --version
cargo --version

Clone and configure

git clone <repository-url>
cd qimem
cp .env.example .env

Run with cargo

QIMEM_MODE=stateless cargo run --bin qimem-api

Verify the service

curl -fsS http://localhost:8080/health

Cargo Build Options

Feature Flags

stateful: Enables Postgres key store via SQLx
chacha: Adds ChaCha20-Poly1305 algorithm support (optional)

Example:

cargo build --release --features stateful,chacha

Production Builds

Build optimized binaries:

cargo build --release --bin qauth-api --features stateful

Binary location:

target/release/qauth-api

Strip symbols for smaller size:

strip target/release/qauth-api

Environment Configuration

All QIMEM binaries read configuration from environment variables. Reference .env.example:

.env.example

QIMEM_MODE=stateless
DATABASE_URL=postgres://postgres:postgres@postgres:5432/qimem
QIMEM_BIND=0.0.0.0:8080
RUST_LOG=info

Configuration Reference

QIMEM_MODE

string

default:"stateless"

Storage mode: stateless (in-memory) or stateful (Postgres)

DATABASE_URL

string

required

Postgres connection string (required when QIMEM_MODE=stateful)Format: postgres://user:password@host:port/database

QIMEM_BIND

string

default:"0.0.0.0:8080"

HTTP server bind addressExamples:

0.0.0.0:8080 - Listen on all interfaces
127.0.0.1:8080 - Localhost only
[::]:8080 - IPv6 all interfaces

RUST_LOG

string

default:"info"

Logging level using tracing crateLevels: error, warn, info, debug, traceModule-specific filtering:

RUST_LOG=qimem=debug,sqlx=warn

Production Deployment

Production deployments require careful security configuration. Follow these best practices:

Stateful Mode with Managed Postgres

Provision a managed Postgres instance

Use a managed service like AWS RDS, Google Cloud SQL, or Azure Database for PostgreSQL:

PostgreSQL 14 or later
Encrypted storage at rest
Automated backups enabled
SSL/TLS connections enforced

Configure DATABASE_URL with SSL

DATABASE_URL=postgres://user:[email protected]:5432/qimem?sslmode=require

For mutual TLS:

DATABASE_URL=postgres://user:[email protected]:5432/qimem?sslmode=verify-full&sslrootcert=/path/to/ca.crt

Run migrations

Migrations run automatically on startup. To run manually:

sqlx migrate run --database-url $DATABASE_URL

Security Hardening

Network Security

Deploy behind a reverse proxy (nginx, Envoy, Cloudflare)
Enable TLS 1.3 with strong cipher suites
Use firewall rules to restrict database access
Implement rate limiting to prevent brute force

Key Material Protection

QIMEM uses zeroize::Zeroizing for automatic memory cleanup
No key bytes are logged (enforced by #![deny(unsafe_code)])
Consider hardware security modules (HSMs) for master keys
Rotate signing keys regularly via /v1/auth/keys/rotate

Monitoring and Observability

Health endpoints:

GET /health - Service liveness
GET /ready - Readiness (DB connectivity)
GET /v1/security/health - Security subsystem health

Configure structured logging:

RUST_LOG=qimem=info,tower_http=debug

Integrate with metrics exporters (Prometheus, Datadog, etc.)

Container Orchestration

apiVersion: apps/v1
kind: Deployment
metadata:
  name: qauth-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: qauth-api
  template:
    metadata:
      labels:
        app: qauth-api
    spec:
      containers:
      - name: qauth-api
        image: qimem/qauth-api:latest
        ports:
        - containerPort: 8080
        env:
        - name: QIMEM_MODE
          value: "stateful"
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: qimem-secrets
              key: database-url
        - name: RUST_LOG
          value: "info"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

Health Checks

QIMEM provides multiple health check endpoints for different purposes:

GET /health

object

Basic liveness probe

{"status":"ok"}

Use case: Kubernetes liveness probe, load balancer health check

GET /ready

object

Readiness probe with dependency checks

{"status":"ready"}

Use case: Kubernetes readiness probe, confirms database connectivity in stateful mode

GET /v1/security/health

object

Security subsystem health

{"status":"ok"}

Use case: Monitoring security-specific components

Troubleshooting

Connection refused on port 8080

Cause: Service not running or wrong bind addressSolution:

# Check if process is running
ps aux | grep qimem

# Verify QIMEM_BIND matches your request
echo $QIMEM_BIND

# Check Docker container logs
docker compose logs qimem-api

Database connection failed

Cause: Invalid DATABASE_URL or Postgres not readySolution:

# Test Postgres connectivity
psql $DATABASE_URL -c "SELECT 1;"

# Check Docker Compose health
docker compose ps

# Verify DATABASE_URL format
echo $DATABASE_URL

Build fails with stateful feature

Cause: Missing SQLx dependencies or database not accessible during buildSolution:

# SQLx compile-time verification needs DATABASE_URL
export DATABASE_URL=postgres://postgres:postgres@localhost:5432/qimem

# Or use offline mode
cargo build --features stateful --offline

Permission denied errors in Docker

Cause: Container runs as non-root user qimem (UID 10001)Solution: Ensure mounted volumes have correct permissions:

chown -R 10001:10001 /path/to/volume

Get Started

Core Concepts

Deployment

Installation Methods

Docker (Recommended)

Build from Source

Docker Installation

Docker Compose Services

Build from Source

Cargo Build Options

Environment Configuration

Configuration Reference

Production Deployment

Stateful Mode with Managed Postgres

Security Hardening

Container Orchestration

Health Checks

Troubleshooting

Next Steps

Quickstart Guide

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

​Installation Methods

Docker (Recommended)

Build from Source

​Docker Installation

​Docker Compose Services

​Build from Source

​Cargo Build Options

​Environment Configuration

​Configuration Reference

​Production Deployment

​Stateful Mode with Managed Postgres

​Security Hardening

​Container Orchestration

​Health Checks

​Troubleshooting

​Next Steps

Quickstart Guide

API Reference

Build docs developers (and LLMs) love

Installation Methods

Docker Installation

Docker Compose Services

Build from Source

Cargo Build Options

Environment Configuration

Configuration Reference

Production Deployment

Stateful Mode with Managed Postgres

Security Hardening

Container Orchestration

Health Checks

Troubleshooting

Next Steps