A production-ready Rust REST API boilerplate using Axum, SeaORM, and JWT authentication, built with Hexagonal Architecture (Ports & Adapters) and DDD principles.
# 1. Setup environment
cp .env.example .env
# 2a. Run everything with Docker (PostgreSQL + migrations + API)
docker compose up --build
# 2b. Or run locally without any database (in-memory, data lost on restart)
STORAGE=memory cargo run
# 2c. Or run locally against the Docker database
docker compose up -d postgresql
(cd migration && cargo run -- up)
cargo runSwagger UI: http://localhost:3000/api-docs
| Command | Description |
|---|---|
cargo run |
Run the application |
cargo xtask check |
Format, lint, test and doc checks (as CI) |
cargo xtask fix |
Auto-fix formatting and clippy suggestions |
cargo build --release |
Build for production |
cd migration && cargo run -- up |
Apply database migrations |
docker compose up --build |
Run the full stack in Docker |
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health |
- | Health check |
| POST | /register |
- | Create an account |
| POST | /login |
- | Get a bearer token |
| GET | /users |
Admin | List users (paginated) |
| POST | /users |
Admin | Create a user |
| GET | /users/{id} |
Owner / Admin | Get a user |
| PUT | /users/{id} |
Owner / Admin | Update a user |
To get an admin, set ADMIN_EMAIL and ADMIN_PASSWORD (see .env.example); the account is created or promoted on startup.
Errors follow the JSON:API error format.
src/
├── domain/ # Core business logic (entities, value objects, ports)
├── app/ # Use cases & orchestration
├── infra/ # Database, JWT & config adapters
├── presentation/ # HTTP router, handlers, middleware, extractors
└── bootstrap.rs # Dependency injection wiring
migration/ # SeaORM migrations + CLI
tests/ # HTTP-level integration tests
For architecture, conventions and development patterns, see AGENTS.md.
MIT