112 lines
2.8 KiB
Markdown
112 lines
2.8 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
cargo install cargo-generate
|
||
```
|
||
|
||
Generate a new project from this template:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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`:
|
||
|
||
```rust
|
||
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.
|