axum-conf

Production-ready web services with Axum — batteries included.

Build Kubernetes-native Rust services without the boilerplate. axum-conf gives you health probes, metrics, security headers, rate limiting, and more — all configured through simple TOML.

                              axum-conf
    ┌─────────────────────────────────────────────────────────┐
    │                                                         │
    │  ┌─────────────┐   ┌──────────────┐   ┌─────────────┐   │
    │  │   Config    │──▶│ FluentRouter │──▶│  Middleware │   │
    │  │   (TOML)    │   │   Builder    │   │    Stack    │   │
    │  └─────────────┘   └──────────────┘   └─────────────┘   │
    │                           │                             │
    │                           ▼                             │
    │  ┌─────────────────────────────────────────────────┐    │
    │  │              Production-Ready Server            │    │
    │  │  • Health probes  • Metrics  • Security headers │    │
    │  │  • Rate limiting  • CORS     • Graceful shutdown│    │
    │  └─────────────────────────────────────────────────┘    │
    │                                                         │
    └─────────────────────────────────────────────────────────┘

Why axum-conf?

• Zero boilerplate: Get liveness probes, Prometheus metrics, and security headers without writing middleware
• Kubernetes-native: Built for container deployments with proper health checks and graceful shutdown
• Configuration-driven: Change behavior through TOML files, not code changes

Quick Start

1. Add to Cargo.toml:

[dependencies]
axum-conf = "0.3"
axum = "0.8"
tokio = { version = "1", features = ["full"] }

2. Create config/dev.toml:

[http]
bind_port = 3000
max_payload_size_bytes = "1MiB"

3. Write src/main.rs:

use axum::{Router, routing::get};
use axum_conf::{Config, Result, FluentRouter};

async fn hello() -> &'static str {
    "Hello, World!"
}

#[tokio::main]
async fn main() -> Result<()> {
    let config = Config::default();
    config.setup_tracing();

    FluentRouter::without_state(config)?
        .route("/", get(hello))
        .setup_middleware()
        .await?
        .start()
        .await
}

4. Run:

RUST_ENV=dev cargo run

5. Test it:

curl http://localhost:3000/        # Your handler
curl http://localhost:3000/live    # Liveness probe
curl http://localhost:3000/ready   # Readiness probe
curl http://localhost:3000/metrics # Prometheus metrics

What You Get

Cargo Features

Enable optional capabilities by category:

Core Features

Middleware Features

Feature Groups

# Example: Production setup with PostgreSQL
axum-conf = { version = "0.3", features = ["production", "postgres"] }

Feature Compatibility

Most features work together, with one important exception:

Important: keycloak and basic-auth are mutually exclusive. Choose one authentication method per application.

Examples

Run the examples to see axum-conf in action:

# Basic hello world
cargo run --example hello_world

# Application state management
cargo run --example with_state

# JSON REST API
cargo run --example json_api

# Middleware configuration (requires features)
cargo run --example with_middleware --features "cors,compression,rate-limiting"

Configuration Example

# config/prod.toml
[http]
bind_addr = "0.0.0.0"
bind_port = 8080
max_payload_size_bytes = "32KiB"
request_timeout = "30s"
max_requests_per_sec = 1000

[http.cors]
allowed_origins = ["https://app.example.com"]
allowed_methods = ["GET", "POST", "PUT", "DELETE"]

[database]
url = "{{ DATABASE_URL }}"
max_pool_size = 10

[logging]
format = "json"

Custom Tracing Layers

The default setup_tracing() configures logging based on your LoggingConfig. When you need additional tracing layers (OpenTelemetry, file appenders, custom filters), use setup_tracing_with():

use axum_conf::Config;
use tracing_subscriber::layer::SubscriberExt;

let config = Config::default();

// Add custom layers while keeping the configured fmt layer and env filter
config.setup_tracing_with(|subscriber| {
    subscriber
        .with(tracing_opentelemetry::layer().with_tracer(tracer))
        .with(my_file_appender_layer)
});

The callback receives a TracingBase subscriber with the fmt layer (respecting your logging.format setting) and EnvFilter already applied. Add your layers with .with() and return the result.

Documentation

Minimal Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  template:
    spec:
      containers:
      - name: app
        image: my-service:latest
        ports:
        - containerPort: 8080
        env:
        - name: RUST_ENV
          value: "prod"
        livenessProbe:
          httpGet:
            path: /live
            port: 8080
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
      terminationGracePeriodSeconds: 35

License

MIT