https://github.com/riktastic/axium
An example API built with Rust, Axum, SQLx, and PostgreSQL.
https://github.com/riktastic/axium
api axum boilerplate docker docker-compose https jwt postgresql quickstart rust sqlx template tls
Last synced: 2 months ago
JSON representation
An example API built with Rust, Axum, SQLx, and PostgreSQL.
- Host: GitHub
- URL: https://github.com/riktastic/axium
- Owner: Riktastic
- License: mit
- Created: 2025-01-30T21:43:27.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-03-06T05:29:53.000Z (3 months ago)
- Last Synced: 2025-03-27T21:48:08.984Z (3 months ago)
- Topics: api, axum, boilerplate, docker, docker-compose, https, jwt, postgresql, quickstart, rust, sqlx, template, tls
- Language: Rust
- Homepage: https://github.com/Riktastic/Axium
- Size: 355 KB
- Stars: 9
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🦖 Axium
**An example API built with Rust, Axum, SQLx, and PostgreSQL.**
[](https://opensource.org/licenses/MIT)
## Summary
Axium is a high-performance, security-focused API boilerplate built using Rust, Axum, SQLx, and PostgreSQL. It provides a ready-to-deploy solution with modern best practices, including JWT authentication, role-based access control (RBAC), structured logging, and enterprise-grade security. With a focus on developer experience, Axium offers auto-generated API documentation, efficient database interactions, and an ergonomic code structure for ease of maintenance and scalability.
## Table of Contents
1. [🚀 Core Features](#-core-features)
2. [🛠️ Technology Stack](#%EF%B8%8F-technology-stack)
3. [📂 Project Structure](#-project-structure)
4. [🌐 Default API Endpoints](#-default-api-endpoints)
5. [📦 Installation & Usage](#-installation--usage)
- [🐳 Docker setup guide](/documentation/installation_docker.md)
- [🐧 Ubuntu setup guide](/documentation/installation_ubuntu.md)
- [🖥️ Windows setup guide](/documentation/installation_windows.md)
- [🔐 Default Accounts](#-default-accounts)
- [⚙️ Configuration](#%EF%B8%8F-configuration)
7. [🤝 Contributing](#-contributing)
- [📝 How to Contribute](#-how-to-contribute)
- [🔍 Code Style](#-code-style)
- [🛠️ Reporting Bugs](#%EF%B8%8F-reporting-bugs)
- [💬 Discussion](#-discussion)
- [🧑💻 Code of Conduct](#-code-of-conduct)
## 🚀 Core Features
### **Effortless Deployment**
_From zero to production in minutes_
- 🐳 Docker Compose stack with pre-configured services
- 20-minute setup timeline with `docker-compose up` simplicity
### **Developer-First API Experience**
_Spec-driven development workflow_
- Auto-generated OpenAPI 3.1 specifications
- Interactive Swagger UI endpoint at `/docs`
```rust
// Endpoint registration example
.route("/docs", get(serve_swagger_ui))
```
### **Enterprise-Grade Security**
_Security by design architecture_
- JWT authentication with Argon2id password hashing (OWASP recommended)
- TLS 1.3/HTTP2 via AWS-LC (FIPS 140-3 compliant cryptography)
- Key rotation & expiration
- Role-Based Access Control (RBAC) implementation:
```rust
.layer(middleware::from_fn(|req, next|
authorize(req, next, vec![1, 2]) // Admin+Mod roles
))
```
### **PostgreSQL Integration**
_Relational data made simple_
- SQLx-powered async database operations
- Migration system with transactional safety
- Connection pooling for high concurrency
### **Performance Optimizations**
_Engineered for speed at scale_
- Brotli compression (11-level optimization)
- Intelligent request caching strategies
- Zero-copy deserialization pipelines
### **Operational Visibility**
_Production monitoring made easy_
- Docker-healthcheck compatible endpoint:
```json
{
"status": "degraded",
"details": {
"database": {"status": "ok"},
"memory": {"available_mb": 21613, "status": "normal"},
"cpu_usage": {"available_percentage": "9.85", "status": "low"},
"disk_usage": {"used_percentage": "74.00", "status": "ok"}
}
}
```
### **Developer Ergonomics**
_Code with confidence_
- Context-aware user injection system:
```rust
async fn create_todo(
Extension(User { id, role, .. }): Extension, // Auto-injected
Json(payload): Json
) -> Result {
// Business logic with direct user context
}
```
- Structured logging with OpenTelemetry integration
- Compile-time configuration validation
### **Maintenance & Compliance**
_Future-proof codebase management_
- Security-focused dependency tree (cargo-audit compliant)
- Comprehensive inline documentation:
```rust
/// JWT middleware - Validates Authorization header
/// # Arguments
/// * `req` - Incoming request
/// * `next` - Next middleware layer
/// # Security
/// - Validates Bearer token format
/// - Checks token expiration
/// - Verifies cryptographic signature
```
## 🛠️ Technology stack
| Category | Key Technologies |
|-----------------------|---------------------------------|
| Web Framework | Axum 0.8 + Tower |
| Database | PostgreSQL + SQLx 0.8 |
| Security | JWT + Argon2 + Rustls |
| Monitoring | Tracing + Sysinfo |
## 📂 Project structure
```
axium/ # Root project directory
├── 📁 migrations/ # Database schema migrations (SQLx)
│
├── 📁 src/ # Application source code
│ ├── 📁 core/ # Core application infrastructure
│ │ ├── config.rs # Configuration loader (.env, env vars)
│ │ └── server.rs # HTTP/HTTPS server initialization
│ │
│ ├── 📁 database/ # Database access layer
│ │ ├── connection.rs # Connection pool management
│ │ ├── queries/ # SQL query modules
│ │ └── models.rs # Database entity definitions
│ │
│ ├── 📁 middlewares/ # Axum middleware components
│ ├── 📁 routes/ # API endpoint routing
│ │ └── mod.rs # Route aggregator
│ │
│ ├── 📁 handlers/ # Request handlers
│ │
│ ├── 📁 utils/ # Common utilities
│ │
│ └── main.rs # Application entry point
│
├── 📄 .env # Environment configuration
├── 📄 .env.example # Environment template
├── 📄 Dockerfile # Production container build
├── 📄 docker-compose.yml # Local development stack
└── 📄 Cargo.toml # Rust dependencies & metadata
```
Each folder has a detailed README.md file which explains the folder in more detail.
## 🌐 Default API endpoints
| Method | Endpoint | Auth Required | Administrator only | Description |
|--------|------------------------|---------------|-------------------|--------------------------------------|
| POST | `/signin` | 🚫 | 🚫 | Authenticate user and get JWT token |
| GET | `/protected` | ✅ | 🚫 | Test endpoint for authenticated users |
| GET | `/health` | 🚫 | 🚫 | System health check with metrics |
| | | | | |
| **Apikey routes** | | | | |
| GET | `/apikeys/all` | ✅ | 🚫 | Get all apikeys of the current user. |
| POST | `/apikeys/` | ✅ | 🚫 | Create a new apikey. |
| GET | `/apikeys/{id}` | ✅ | 🚫 | Get an apikey by ID. |
| DELETE | `/apikeys/{id}` | ✅ | 🚫 | Delete an apikey by ID. |
| POST | `/apikeys/rotate/{id}` | ✅ | 🚫 | Rotates an API key, disables the old one (grace period 24 hours), returns a new one. |
| | | | | |
| **User routes** | | | | |
| GET | `/users/all` | ✅ | ✅ | Get all users. |
| POST | `/users/` | ✅ | ✅ | Create a new user. |
| GET | `/users/{id}` | ✅ | ✅ | Get a user by ID. |
| DELETE | `/users/{id}` | ✅ | ✅ | Delete a user by ID. |
| | | | | |
| **Usage routes** | | | | |
| GET | `/usage/lastweek` | ✅ | 🚫 | Amount of API calls withim the last week of the current user. |
| GET | `/usage/lastday` | ✅ | 🚫 | Amount of API calls within last day of the current user. |
| | | | | |
| **Todo routes** | | | | |
| GET | `/todos/all` | ✅ | 🚫 | Get all todos of the current user. |
| POST | `/todos/` | ✅ | 🚫 | Create a new todo. |
| GET | `/todos/{id}` | ✅ | 🚫 | Get a todo by ID. |
| DELETE | `/todos/{id}` | ✅ | 🚫 | Delete a todo by ID. |
## 📦 Installation & usage
To get started with Axium, you'll need to install it on your system. We provide detailed installation guides for different environments:
- **Docker setup**: Follow the instructions in [Docker setup guide](/documentation/installation_docker.md) to run Axium using Docker Compose.
- **Ubuntu setup**: For users on Ubuntu or other Debian-based systems, refer to the [Ubuntu setup Guide](/documentation/installation_ubuntu.md).
- **Windows setup**: Windows users can find their setup instructions in the [Windows setup guide](/documentation/installation_windows.md).
These guides cover cloning the repository, setting up the environment, configuring the database, and running the application.
### 🔐 Default accounts
**Warning:** These accounts should only be used for initial testing. Always change or disable them in production environments.
| Email | Password | Role |
|---------------------|----------|----------------|
| `[email protected]` | `test` | User |
| `[email protected]` | `test` | Administrator |
⚠️ **Security recommendations:**
1. Rotate passwords immediately after initial setup.
2. Disable default accounts before deploying to production.
3. Implement proper user management endpoints.
#### Administrative password resets
*For emergency access recovery only*
1. **Database Access**
Connect to PostgreSQL using privileged credentials:
```bash
psql -U admin_user -d axium_db -h localhost
```
2. **Secure Hash Generation**
Use the integrated CLI tool (never user online generators):
```bash
cargo run --bin argon2-cli -- "new_password"
# Output: $argon2id$v=19$m=19456,t=2,p=1$b2JqZWN0X2lkXzEyMzQ1$R7Zx7Y4W...
```
3. **Database Update**
```sql
UPDATE users
SET
password_hash = '$argon2id...',
updated_at = NOW()
WHERE email = '[email protected]';
```
4. **Verification**
- Immediately test new credentials
- Force user password change on next login
### ⚙️ Configuration
Create a .env file in the root of the project or configure the application using environment variables.
Make sure to change the `JWT_SECRET_KEY`.
```env
# ==============================
# ⚙️ GENERAL CONFIGURATION
# ==============================
ENVIRONMENT="development" # "production"
# ==============================
# 🌍 SERVER CONFIGURATION
# ==============================
# IP address the server will bind to (0.0.0.0 allows all network interfaces)
SERVER_IP="0.0.0.0"
# Port the server will listen on
SERVER_PORT="3000"
# Enable tracing for debugging/logging (true/false)
SERVER_TRACE_ENABLED=true
# Amount of threads used to run the server
SERVER_WORKER_THREADS=2
# ==============================
# 🛢️ DATABASE CONFIGURATION
# ==============================
# PostgreSQL connection URL (format: postgres://user:password@host/database)
DATABASE_URL="postgres://postgres:1234@localhost/database_name"
# Maximum number of connections in the database pool
DATABASE_MAX_CONNECTIONS=20
# Minimum number of connections in the database pool
DATABASE_MIN_CONNECTIONS=5
# ==============================
# 🔒 HTTPS CONFIGURATION
# ==============================
# Enable HTTPS (true/false)
SERVER_HTTPS_ENABLED=false
# Enable HTTP/2 when using HTTPS (true/false)
SERVER_HTTPS_HTTP2_ENABLED=true
# Path to the SSL certificate file (only used if SERVER_HTTPS_ENABLED=true)
SERVER_HTTPS_CERT_FILE_PATH=cert.pem
# Path to the SSL private key file (only used if SERVER_HTTPS_ENABLED=true)
SERVER_HTTPS_KEY_FILE_PATH=key.pem
# ==============================
# 🚦 RATE LIMIT CONFIGURATION
# ==============================
# Maximum number of requests allowed per period
SERVER_RATE_LIMIT=5
# Time period (in seconds) for rate limiting
SERVER_RATE_LIMIT_PERIOD=1
# ==============================
# 📦 COMPRESSION CONFIGURATION
# ==============================
# Enable Brotli compression (true/false)
SERVER_COMPRESSION_ENABLED=true
# Compression level (valid range: 0-11, where 11 is the highest compression)
SERVER_COMPRESSION_LEVEL=6
# ==============================
# 🔑 AUTHENTICATION CONFIGURATION
# ==============================
# JWT secret key.
JWT_SECRET_KEY="Change me!"
```
## 🤝 Contributing
We welcome contributions to the Axium project! Whether it's fixing bugs, improving documentation, or adding new features, your help is greatly appreciated. Please follow these guidelines to ensure a smooth contribution process.
### 📝 How to Contribute
1. **Fork the Repository**
Start by forking the repository to your own GitHub account.
2. **Clone Your Fork**
Clone your forked repository to your local machine:
```bash
git clone https://github.com/your-username/Axium.git
cd Axium
```
3. **Create a New Branch**
Create a new branch for your feature or bug fix:
```bash
git checkout -b feature-name
```
4. **Make Your Changes**
Make the necessary changes to the code or documentation. Make sure to write tests for new features and adhere to the existing code style.
5. **Commit Your Changes**
Commit your changes with a clear, descriptive message:
```bash
git commit -m "Add feature XYZ or fix issue ABC"
```
6. **Push to Your Fork**
Push your changes to your fork:
```bash
git push origin feature-name
```
7. **Open a Pull Request**
Open a pull request against the `main` branch of the original repository. In the description, provide details about the changes you made, the problem they solve, and any testing you performed.
### 🔍 Code Style
- Follow the **Rust style guidelines** outlined in the [Rust Style Guide](https://doc.rust-lang.org/1.0.0/style/).
- Use **cargo fmt** to automatically format your code:
```bash
cargo fmt
```
- Write **meaningful commit messages** that describe the changes you've made.
### 🛠️ Reporting Bugs
If you encounter a bug or issue, please check if it has already been reported in the [GitHub issues](https://github.com/Riktastic/Axium/issues). If not, create a new issue, providing the following information:
- A clear description of the problem.
- Steps to reproduce the issue.
- Expected vs. actual behavior.
- Any relevant logs or error messages.
### 💬 Discussion
Feel free to open discussions in the [Discussions](https://github.com/Riktastic/Axium/discussions) section for general questions, ideas, or advice on how to improve the project.
### 🧑💻 Code of Conduct
Please be respectful and follow the [Code of Conduct](https://www.contributor-covenant.org/) while interacting with other contributors. Let's maintain a positive and welcoming environment.
### 🎉 Thanks for Contributing!
Your contributions help make Axium better for everyone! 🙏