Compare commits
3 Commits
ffc5b946c2
...
97854359bf
| Author | SHA1 | Date | |
|---|---|---|---|
|
97854359bf | ||
|
|
bf394f7dbc | ||
|
|
9096d6a3e9 |
20
.gitignore.liquid
Normal file
20
.gitignore.liquid
Normal file
@@ -0,0 +1,20 @@
|
||||
# Rust
|
||||
/target
|
||||
|
||||
# Env files
|
||||
.env*
|
||||
!.env.example
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
|
||||
# Build artifacts
|
||||
*.exe
|
||||
*.dll
|
||||
*.so
|
||||
*.dylib
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
*.tmp
|
||||
21
README.md
21
README.md
@@ -24,7 +24,7 @@ cargo install cargo-generate
|
||||
Generate a new project from this template:
|
||||
|
||||
```bash
|
||||
cargo generate --git <your-template-repo-url>
|
||||
cargo generate --git https://gitea.fasharp.io/fa-sharp/axum-template
|
||||
```
|
||||
|
||||
You'll be prompted for:
|
||||
@@ -35,16 +35,9 @@ You'll be prompted for:
|
||||
- **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.
|
||||
Configuration is loaded from environment variables and validated in the `config.rs` file. The variable prefix is configurable during template generation.
|
||||
|
||||
Example with `APP` prefix:
|
||||
|
||||
@@ -58,18 +51,20 @@ APP_PORT=8080
|
||||
APP_LOG_LEVEL=info
|
||||
```
|
||||
|
||||
In development, you can use the `.env` file.
|
||||
In development, you can use the `.env` file to set environment variables.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── src/
|
||||
│ ├── main.rs # Entry point, server setup
|
||||
│ ├── lib.rs # App initialization
|
||||
│ ├── routes/ # API routes
|
||||
│ ├── config.rs # Configuration management
|
||||
│ └── state.rs # Application state
|
||||
│ ├── lib.rs # Axum server setup
|
||||
│ ├── main.rs # Entry point
|
||||
│ └── state.rs # Axum server state
|
||||
├── Cargo.toml # Dependencies
|
||||
├── .env # Local environment variables
|
||||
└── .env.example # Example environment variables
|
||||
```
|
||||
|
||||
|
||||
@@ -1,255 +0,0 @@
|
||||
# Axum Template Usage Guide
|
||||
|
||||
This repository is a **cargo-generate** template for creating new Axum web services with a pre-configured, production-ready setup.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Install `cargo-generate`:
|
||||
|
||||
```bash
|
||||
cargo install cargo-generate
|
||||
```
|
||||
|
||||
### Generate a New Project
|
||||
|
||||
#### From a Git Repository (Recommended for Production Use)
|
||||
|
||||
```bash
|
||||
cargo generate --git https://gitea.fasharp.io/fa-sharp/axum-template
|
||||
```
|
||||
|
||||
#### From Local Path (For Testing)
|
||||
|
||||
```bash
|
||||
cargo generate --path /path/to/axum-template
|
||||
```
|
||||
|
||||
### Interactive Prompts
|
||||
|
||||
When you run `cargo generate`, you'll be prompted for:
|
||||
|
||||
1. **Project name**: The name of your new project (e.g., `my-api-server`)
|
||||
2. **Project description**: Brief description (e.g., "REST API for user management")
|
||||
3. **Environment variable prefix**: Prefix for configuration env vars (e.g., `APP` → `APP_HOST`, `APP_PORT`)
|
||||
4. **Default port**: Server's default port (e.g., `8080`)
|
||||
5. **Default log level**: Choose from `trace`, `debug`, `info`, `warn`, or `error`
|
||||
6. **Include aide**: Whether to include OpenAPI documentation support (`true` or `false`)
|
||||
|
||||
### Non-Interactive Mode
|
||||
|
||||
You can skip prompts by providing values via CLI:
|
||||
|
||||
```bash
|
||||
cargo generate --git <repo-url> \
|
||||
--name my-service \
|
||||
--define project-description="My awesome service" \
|
||||
--define env_prefix="API" \
|
||||
--define default_port="3000" \
|
||||
--define default_log_level="info" \
|
||||
--define include_aide=true
|
||||
```
|
||||
|
||||
## Generated Project Structure
|
||||
|
||||
```
|
||||
my-project/
|
||||
├── src/
|
||||
│ ├── main.rs # Application entry point with server setup
|
||||
│ ├── lib.rs # App initialization and plugin registration
|
||||
│ ├── config.rs # Configuration management (figment-based)
|
||||
│ └── state.rs # Application state management
|
||||
├── Cargo.toml # Dependencies (customized based on your choices)
|
||||
├── .env.example # Example environment variables
|
||||
├── .gitignore # Pre-configured for Rust projects
|
||||
└── README.md # Project-specific README
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The generated project uses environment variables for configuration. The prefix is customizable during generation.
|
||||
|
||||
Example with `APP` prefix:
|
||||
|
||||
```bash
|
||||
# Required
|
||||
APP_API_KEY=your-secret-api-key
|
||||
|
||||
# Optional (defaults are set during template generation)
|
||||
APP_HOST=127.0.0.1
|
||||
APP_PORT=8080
|
||||
APP_LOG_LEVEL=info
|
||||
```
|
||||
|
||||
In development, copy `.env.example` to `.env`:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your values
|
||||
```
|
||||
|
||||
## Features Included
|
||||
|
||||
### Core Features (Always Included)
|
||||
|
||||
- **Axum 0.8** - Modern, ergonomic web framework
|
||||
- **Environment-based Config** - `figment` for flexible configuration
|
||||
- **Structured Logging** - `tracing` with JSON output in production
|
||||
- **Graceful Shutdown** - Handles SIGTERM, SIGINT, and Ctrl-C
|
||||
- **Plugin Architecture** - `axum-app-wrapper` for modular initialization
|
||||
- **Rust 2024 Edition** - Latest language features
|
||||
|
||||
### Optional Features
|
||||
|
||||
- **OpenAPI Documentation** - `aide` and `schemars` (optional during generation)
|
||||
|
||||
## Next Steps After Generation
|
||||
|
||||
1. **Navigate to your project**:
|
||||
```bash
|
||||
cd my-project
|
||||
```
|
||||
|
||||
2. **Configure environment**:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# Edit .env with your actual values
|
||||
```
|
||||
|
||||
3. **Run in development**:
|
||||
```bash
|
||||
cargo run
|
||||
```
|
||||
|
||||
4. **Add your routes**:
|
||||
- Create a new module for your routes
|
||||
- Implement a plugin function
|
||||
- Register it in `src/lib.rs`
|
||||
|
||||
5. **Build for production**:
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
## Customization Tips
|
||||
|
||||
### Adding Routes
|
||||
|
||||
Create a new module (e.g., `src/routes.rs`):
|
||||
|
||||
```rust
|
||||
use axum::{routing::get, Router};
|
||||
use axum_app_wrapper::AdHocPlugin;
|
||||
use crate::state::AppState;
|
||||
|
||||
pub fn plugin() -> AdHocPlugin<AppState> {
|
||||
AdHocPlugin::new().on_router(|router| async move {
|
||||
let routes = Router::new()
|
||||
.route("/health", get(health_check));
|
||||
|
||||
Ok(router.merge(routes))
|
||||
})
|
||||
}
|
||||
|
||||
async fn health_check() -> &'static str {
|
||||
"OK"
|
||||
}
|
||||
```
|
||||
|
||||
Register it in `src/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(routes::plugin()) // Add this line
|
||||
.init()
|
||||
.await?;
|
||||
|
||||
let app_config = state.config.to_owned();
|
||||
Ok((router.with_state(state), app_config, on_shutdown))
|
||||
}
|
||||
```
|
||||
|
||||
### Adding Dependencies
|
||||
|
||||
Just edit `Cargo.toml` as normal:
|
||||
|
||||
```bash
|
||||
cargo add sqlx --features postgres,runtime-tokio
|
||||
```
|
||||
|
||||
### Changing the Environment Prefix
|
||||
|
||||
The prefix is baked in during template generation. To change it later, search and replace in:
|
||||
- `src/config.rs` (the `extract_config` function)
|
||||
- `.env.example`
|
||||
|
||||
## Publishing Your Template
|
||||
|
||||
### GitHub
|
||||
|
||||
1. Push this directory to GitHub
|
||||
2. Enable "Template repository" in Settings
|
||||
3. Others can use: `cargo generate --git https://github.com/you/axum-template`
|
||||
|
||||
### GitLab/Gitea
|
||||
|
||||
1. Push to your instance
|
||||
2. Share the URL: `cargo generate --git https://gitea.example.com/you/axum-template`
|
||||
|
||||
### Private Repositories
|
||||
|
||||
cargo-generate supports authentication:
|
||||
|
||||
```bash
|
||||
cargo generate --git https://github.com/you/private-template --branch main
|
||||
# You'll be prompted for credentials if needed
|
||||
```
|
||||
|
||||
## Template Maintenance
|
||||
|
||||
### Updating Dependencies
|
||||
|
||||
Update the versions in `Cargo.toml.liquid` and commit:
|
||||
|
||||
```bash
|
||||
# Edit Cargo.toml.liquid
|
||||
git add Cargo.toml.liquid
|
||||
git commit -m "Update dependencies"
|
||||
git push
|
||||
```
|
||||
|
||||
### Testing the Template
|
||||
|
||||
Generate a test project locally:
|
||||
|
||||
```bash
|
||||
cargo generate --path . --name test-project --define include_aide=true
|
||||
cd test-project
|
||||
cargo check
|
||||
cargo test
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to parse Cargo.toml"
|
||||
|
||||
- Make sure template syntax is on separate lines in `.liquid` files
|
||||
- Cargo-generate needs `.liquid` extension for files with Jinja2 syntax
|
||||
|
||||
### Missing Imports in Generated Code
|
||||
|
||||
- Check that Rust edition is set to 2024 in `Cargo.toml.liquid`
|
||||
- Edition 2024 includes `Future` in the prelude
|
||||
|
||||
### Conditional Features Not Working
|
||||
|
||||
- Use `{% if variable %}...{% endif %}` syntax
|
||||
- Keep conditionals on their own lines in TOML files
|
||||
- Test with both `true` and `false` values
|
||||
|
||||
## License
|
||||
|
||||
Configure the license for your template as appropriate. The generated projects will inherit this license unless modified.
|
||||
Reference in New Issue
Block a user