Axum Web Service Template

A production-ready template for building web services with Rust and Axum.

Features

• Axum - Fast and ergonomic web framework
• Configuration Management - Environment-based config with figment
• Structured Logging - JSON logging in production with tracing
• Graceful Shutdown - Handles SIGTERM and SIGINT signals
• ️Plugin Architecture - Modular app initialization with axum-app-wrapper
• Optional OpenAPI - API documentation with aide (optional)

Usage

Using cargo-generate

Install cargo-generate if you haven't already:

cargo install cargo-generate

Generate a new project from this template:

cargo generate --git <your-template-repo-url>

You'll be prompted for:

• Project name: The name of your new project
• Project description: A brief description
• Environment variable prefix: Prefix for env vars (e.g., APP for APP_HOST, APP_PORT)
• Default port: The server's default port
• Default log level: trace, debug, info, warn, or error
• Include aide: Whether to include OpenAPI documentation support

Manual Setup

1. Clone or download this repository
2. Update Cargo.toml with your project name and details
3. Copy .env.example to .env and configure your environment variables
4. Run cargo build

Configuration

Configuration is loaded from environment variables. The prefix is configurable during template generation.

Example with APP prefix:

# Required
APP_API_KEY=your-secret-key

# Optional (defaults shown)
APP_HOST=127.0.0.1
APP_PORT=8080
APP_LOG_LEVEL=info

In development, you can use a .env file (copy from .env.example).

Project Structure

.
├── src/
│   ├── main.rs       # Entry point, server setup
│   ├── lib.rs        # App initialization
│   ├── config.rs     # Configuration management
│   └── state.rs      # Application state
├── Cargo.toml        # Dependencies
└── .env.example      # Example environment variables

Development

# Run in development mode (loads .env file)
cargo run

# Run with custom log level
RUST_LOG=debug cargo run

# Build for production
cargo build --release

Adding Routes

This template uses axum-app-wrapper for modular initialization. To add routes:

1. Create a new plugin in a separate module
2. Register it in lib.rs:

pub async fn create_app() -> anyhow::Result<(axum::Router, AppConfig, impl Future + Send)> {
    let (router, state, on_shutdown) = App::new()
        .register(config::plugin())
        .register(your_routes::plugin())  // Add your plugin here
        .init()
        .await?;
    
    let app_config = state.config.to_owned();
    Ok((router.with_state(state), app_config, on_shutdown))
}

License

Configure your license as needed.