Deep Dive

Deployment Guide

Docker multi-stage builds, Kubernetes manifests, and production deployment patterns for Ranvier.

Core Concepts

Docker Multi-Stage Build

Stage 1 (Builder): rust:1.93-bookworm with cargo-chef for dependency caching.
Stage 2 (Runtime): debian:bookworm-slim with non-root user and HEALTHCHECK.
Dependency caching: Only rebuild when Cargo.toml/Cargo.lock change.

Kubernetes Manifests

Deployment: Readiness, liveness, and startup probes with Prometheus annotations.
Service: ClusterIP with http (80→3000) and inspector (3001) ports.
ConfigMap: ranvier.toml with server, logging, inspector, and telemetry sections.
HPA: CPU/memory-based autoscaling with scale-up and scale-down policies.

Configuration in Production

Profile activation: RANVIER_PROFILE=prod selects [profile.prod] overrides.
Secrets: Mount as environment variables (RANVIER_TELEMETRY__OTLP_ENDPOINT).
Volume mount: ConfigMap → /app/ranvier.toml for file-based configuration.

Health Probes

/health: Full health status with registered check results.
/ready: Readiness probe — returns 200 when all checks pass.
/live: Liveness probe — always returns 200 (process is alive).
Startup probe: Initial delay for application warmup.

Capability Snapshot

Can

Define typed decision flows with Axon/Transition/Outcome contracts, explicit Bus wiring, and `Never` error type for infallible pipelines. 61 maintained examples covering all 10 crates.
Run protocol-agnostic core circuits through HTTP ingress adapters with dynamic routing, request extractors, lifecycle controls, middleware composition, and per-path policy overrides.
Apply HTTP security/policy stacks with `ranvier-std` Guard nodes (CorsGuard, RateLimit, SecurityHeaders, IpFilter) — visible in Schematic and Inspector Timeline.
Generate OpenAPI docs and Swagger UI from request/response contracts via `ranvier-openapi`.
Serve static directories and SPA fallback with cache/compression options for fullstack-style delivery.
Handle WebSocket/SSE real-time flows and inject connection/session context into Bus.
Build LLM-as-Transition pipelines for AI classification, content moderation, and policy enforcement.
Write in-process HTTP integration tests with `TestApp/TestRequest/TestResponse` and runtime path assertions with `AxonTestKit`/`Timeline`.
Store and query traces with `ranvier-inspector` TraceStore, secure endpoints with BearerAuth, and route alerts via AlertHook/AlertDispatcher.
Run session/job/persistence patterns and resume faulted workflows from checkpoints with PersistenceStore and compensation hooks.
Validate API compatibility and detect structural drift with cargo-semver-checks and schematic diff/policy CLI commands.
Monitor per-node metrics (throughput, latency percentiles, error rate), inspect in-transit payloads, manage dead letters, set conditional breakpoints, and detect stalled nodes through the built-in Inspector REST + WebSocket server.
Register JSON Schema on circuit nodes via `.with_input_schema::<T>()` builder API or `#[transition(schema)]` macro attribute. Inspector serves schema-enriched route metadata (`GET /api/v1/routes`), relays HTTP requests into running circuits (`POST /api/v1/relay`), and generates empty templates or random sample payloads from schema (`POST /api/v1/routes/schema`, `POST /api/v1/routes/sample`).
Configure production infrastructure with `RanvierConfig` (`ranvier.toml` + env overrides + profile system), structured logging (`init_logging()` with JSON/pretty/compact), and optional TLS via `rustls`.
Return RFC 7807 Problem Details error responses with `ProblemDetail`/`IntoProblemDetail`, and retry faulted transitions with `RetryPolicy` (fixed/exponential backoff) via `Axon::then_with_retry()`.
Provide quantitative performance baselines with criterion micro-benchmarks (Axon latency, Bus operations, Transition chains) and Axum/Actix-web comparison servers.
Demonstrate real-world patterns through three reference applications: Todo API (CRUD + JWT auth), Chat Server (multi-room WebSocket), and E-commerce Order Pipeline (4-stage Saga compensation + audit trail + multi-tenancy).
Automate version migration with `ranvier migrate --from 0.20 --to 0.25` for import path replacement, crate dependency swaps. TOML-based migration rules (text_replace, rename_import, warn) with --dry-run mode.
Export Prometheus exposition metrics from Inspector `/metrics` endpoint, auto-initialize OTLP TracerProvider via TelemetryConfig, log HTTP requests with AccessLogGuard path redaction, persist audit events to PostgreSQL with PostgresAuditSink hash-chain integrity, and auto-register OpenAPI SecurityScheme (bearerAuth) with ProblemDetail (RFC 7807) error responses.
Understand framework design philosophy through PHILOSOPHY.md ('Opinionated Core, Flexible Edges' principle) and architecture decision rationale via DESIGN_PRINCIPLES.md (ADR format covering Paradigm Test, Tower Separation, and Opinionated Core enforcement).
Implement authentication using two approaches: Transition-based (examples/auth-transition — Bus context propagation, Schematic visualization, easier testing) or Tower integration (examples/auth-tower-integration — AsyncAuthorizeRequest trait for ecosystem compatibility).
Compare authentication strategies with docs/guides/auth-comparison.md: 7-feature comparison table, performance benchmarks (~1-2μs overhead both), when-to-use decision tree, and migration paths between Transition and Tower approaches.

Cannot yet

Token/claim-to-role mapping for inspector auth headers is not built into core runtime and depends on deployment gateway policy.

Quickstart

# Build
docker build -t my-ranvier-app .

# Run with config
docker run -p 3000:3000 \
  -e RANVIER_PROFILE=prod \
  -e RANVIER_TELEMETRY__OTLP_ENDPOINT=http://otel:4317 \
  my-ranvier-app

# Kubernetes
kubectl apply -f k8s/

Primary Workflow

Copy Dockerfile.example and .dockerignore.example to your project root.
Build Docker image: docker build -t my-ranvier-app .
Create Kubernetes namespace and apply ConfigMap with ranvier.toml.
Apply Deployment, Service, and HPA manifests to the cluster.
Configure Prometheus scraping via pod annotations.
Set up OTLP endpoint for distributed tracing (Jaeger, Tempo, Datadog).
Monitor with /health, /ready, /live endpoints and Inspector /metrics.

Verification Commands

Workspace example build cargo check --workspace
Typed flow example run cargo run -p typed-state-tree
HTTP routing and extractor example run cargo run -p routing-params-demo
HTTP graceful shutdown hooks test cargo test -p ranvier-http
HTTP in-process test harness + health probes cargo test -p ranvier-http --test test_app_health
HTTP request validation feature cargo test -p ranvier-http --features validation
Validation struct-level example run cargo run -p ranvier-http --example validation_struct_level --features validation
Std Guard nodes (CorsGuard/RateLimit/SecurityHeaders/IpFilter) tests cargo test -p ranvier-std guard
OpenAPI generator tests cargo test -p ranvier-openapi
OpenAPI demo compile cargo check -p openapi-demo
Static serving + SPA fallback tests cargo test -p ranvier-http
Static SPA demo compile cargo check -p static-spa-demo
WebSocket ingress upgrade + Event bridge tests cargo test -p ranvier-http
WebSocket ingress demo compile cargo check -p websocket-ingress-demo
Inspector TraceStore + BearerAuth tests cargo test -p ranvier-inspector
Workspace full test sweep cargo test --workspace
Examples smoke baseline (M119) ./scripts/m119_examples_smoke.ps1
Inspector quick-view smoke ./scripts/m131_inspector_quickview_smoke.ps1
Schematic diff/policy smoke ./scripts/m131_schematic_diff_policy_smoke.ps1
Fullstack embedded static smoke ./scripts/m131_fullstack_embedded_smoke.ps1
Runtime timeline integration assertion cargo test -p ranvier-runtime timeline_assertion_works_in_integration_test
M132 SeaORM ecosystem reference run cargo run -p ecosystem-seaorm-demo
M132 Diesel ecosystem reference run cargo run -p ecosystem-diesel-demo
M132 Redis ecosystem reference run cargo run -p ecosystem-redis-demo
M132 NATS ecosystem reference run cargo run -p ecosystem-nats-demo
M132 Meilisearch ecosystem reference run cargo run -p ecosystem-meilisearch-demo
Session pattern example compile cargo check -p session-pattern
Inspector metrics + stall detection tests cargo test -p ranvier-inspector metrics stall
Inspector conditional breakpoint + payload capture tests cargo test -p ranvier-inspector breakpoint payload
Guard nodes demo compile (CorsGuard, RateLimit, SecurityHeaders, IpFilter) cargo check -p guard-demo
Auth JWT role-based demo compile (IamVerifier, IamPolicy, with_iam) cargo check -p auth-jwt-role-demo

Sub-crate Overview

ranvier-core

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-macros

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-runtime

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-http

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-std

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-audit

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-compliance

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-inspector

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier-openapi

Ecosystem: crates.io
Version: 0.30.0
Status: released

ranvier

Ecosystem: crates.io
Version: 0.30.0
Status: released
For latest capability status and artifact versions, check /status.