Rust Axum Server Template

A production-ready Axum web server template with HTTPS and Prometheus metrics support.

Features

• High Performance: Built with Axum and Tokio for maximum performance
• Security First: HTTPS support with external certificate provisioning including certificate validation (no self-signed certificates)
• Observability: Integrated structured logging and error handling
• Health Checks: Built-in health check endpoints for monitoring
• Configuration: Flexible configuration via environment variables and config files
• Docker Ready: Multi-stage Docker builds for production deployment
• Well Documented: Comprehensive documentation and examples
• Memory Optimized: Uses jemalloc for efficient memory allocation in high-concurrency scenarios
• Performance Optimized: TLS session caching, request timeouts, concurrency limits, compression, and graceful shutdown

Quick Start

Using Cargo Generate

cargo install cargo-generate
cargo generate --git https://github.com/ErwanLegrand/rust-axum-server-template

Manual Setup

git clone https://github.com/ErwanLegrand/rust-axum-server-template
cd rust-axum-server-template
cargo run

The server will start on http://localhost:3000 with the following endpoints:

• GET / - Root endpoint
• GET /health - Health check endpoint

Configuration

Configure the server using environment variables:

# Server configuration
AXUM_HOST=0.0.0.0
AXUM_HTTP_PORT=3000
AXUM_HTTPS_PORT=3443

# TLS configuration
AXUM_TLS_ENABLED=true
AXUM_CERT_PATH=/path/to/cert.pem
AXUM_KEY_PATH=/path/to/key.pem

# Logging
AXUM_LOG_LEVEL=info
AXUM_METRICS_ENABLED=true

Configuration File

Create a config.toml file:

host = "0.0.0.0"
http_port = 3000
https_port = 3443
tls_enabled = true
cert_path = "/path/to/cert.pem"
key_path = "/path/to/key.pem"
log_level = "info"
metrics_enabled = true

HTTPS Setup

Manual TLS (Required)

This server requires external certificate provisioning for security. Provide your own certificates:

export AXUM_TLS_ENABLED=true
export AXUM_CERT_PATH=/path/to/cert.pem
export AXUM_KEY_PATH=/path/to/key.pem

Note: Self-signed certificates are not supported. You must provide valid certificates from a trusted certificate authority. Certificates are validated for expiration and validity.

Docker Deployment

Build and run with Docker:

# Build the image
docker build -t axum-server .

# Run the container
docker run -p 3000:3000 -p 3443:3443 \
 -e AXUM_TLS_ENABLED=true \
 -e AXUM_CERT_PATH=/path/to/cert.pem \
 -e AXUM_KEY_PATH=/path/to/key.pem \
 axum-server

Performance Features

This server includes several performance optimizations:

Memory Management

Uses jemalloc as the global memory allocator for improved performance in high-concurrency scenarios:

• Reduces memory fragmentation
• Improves allocation performance under load
• Better handling of multi-threaded workloads
• Lower memory usage in long-running processes

Network Performance

• TLS Session Caching: Reduces TLS handshake overhead for repeat connections
• Request Timeouts: Prevents resource exhaustion from slow clients (30-second timeout)
• Concurrency Limits: Limits maximum concurrent connections (1000)
• Response Compression: Automatically compresses responses for better bandwidth utilization
• Connection Pooling: Ready for database/external service integration

Security Performance

• Certificate Validation: Automatic validation of certificate expiration and validity periods
• Efficient TLS: Optimized TLS configuration with session resumption
• Structured Error Handling: Fast error responses with JSON formatting

All performance features are automatically configured and require no additional setup.

Certificate Management

Important: This server follows security best practices by requiring external certificate provisioning with automatic validation. Self-signed certificates are not supported.

Certificate Provisioning

Provide TLS certificates via configuration:

# Certificate and key files
AXUM_CERT_PATH=/path/to/cert.pem
AXUM_KEY_PATH=/path/to/key.pem

Certificate Requirements

• Certificate: PEM format, can include full chain
• Private Key: PEM format, RSA or PKCS8
• Supported Formats: .pem, .crt, .key files

Certificate Rotation

For dynamic certificate updates, restart the server with the new certificate paths or implement your own rotation mechanism.

This approach ensures:

• Better security (no self-signed certificates in production)
• Integration with existing PKI infrastructure
• Compliance with security best practices
• Support for automated certificate rotation via external tools

Monitoring

Health Checks

curl http://localhost:3000/health

Response:

{
 "status": "healthy",
 "timestamp": "2024-01-01T00:00:00.000000000Z",
 "version": "0.1.0"
}

Prometheus Metrics

curl http://localhost:3000/metrics

Development

Running Tests

cargo test

Code Quality

# Format code
cargo fmt

# Lint code
cargo clippy

# Security audit
cargo audit

Project Structure

src/
├── main.rs     # Server entry point with HTTPS/TLS support
├── config.rs    # Configuration management
├── error.rs     # Enhanced error handling with context
├── handlers.rs   # HTTP request handlers

├── tls.rs      # TLS certificate management with session caching
└── metrics.rs.disabled # Prometheus metrics (disabled)

tests/
└── integration.rs  # Integration tests

License

Licensed under MIT OR Apache-2.0

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Security

This template follows security best practices:

• Automatic TLS certificate renewal
• Secure defaults
• Regular security audits
• No secrets in code

For security issues, please email security@erwan.legrand.pm.me

d4ccb68 (Initial release)