{"id":24905785,"url":"https://github.com/riktastic/axium","last_synced_at":"2025-04-14T08:12:47.714Z","repository":{"id":275053255,"uuid":"924916552","full_name":"Riktastic/Axium","owner":"Riktastic","description":"An example API built with Rust, Axum, SQLx, and PostgreSQL.","archived":false,"fork":false,"pushed_at":"2025-03-06T05:29:53.000Z","size":364,"stargazers_count":9,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T21:48:08.984Z","etag":null,"topics":["api","axum","boilerplate","docker","docker-compose","https","jwt","postgresql","quickstart","rust","sqlx","template","tls"],"latest_commit_sha":null,"homepage":"https://github.com/Riktastic/Axium","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Riktastic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-30T21:43:27.000Z","updated_at":"2025-03-06T05:29:56.000Z","dependencies_parsed_at":"2025-01-30T23:18:24.865Z","dependency_job_id":"3308ac7b-b95f-4209-a01f-769721a9dc67","html_url":"https://github.com/Riktastic/Axium","commit_stats":null,"previous_names":["riktastic/rustapi","riktastic/axumrustapi","riktastic/axium"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riktastic%2FAxium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riktastic%2FAxium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riktastic%2FAxium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riktastic%2FAxium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Riktastic","download_url":"https://codeload.github.com/Riktastic/Axium/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248843941,"owners_count":21170495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","axum","boilerplate","docker","docker-compose","https","jwt","postgresql","quickstart","rust","sqlx","template","tls"],"created_at":"2025-02-02T00:25:12.808Z","updated_at":"2025-04-14T08:12:47.684Z","avatar_url":"https://github.com/Riktastic.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🦖 Axium\n**An example API built with Rust, Axum, SQLx, and PostgreSQL.**  \n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Summary\nAxium 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.\n\n## Table of Contents\n1. [🚀 Core Features](#-core-features)\n2. [🛠️ Technology Stack](#%EF%B8%8F-technology-stack)\n3. [📂 Project Structure](#-project-structure)\n4. [🌐 Default API Endpoints](#-default-api-endpoints)\n5. [📦 Installation \u0026 Usage](#-installation--usage)\n   - [🐳 Docker setup guide](/documentation/installation_docker.md)\n   - [🐧 Ubuntu setup guide](/documentation/installation_ubuntu.md)\n   - [🖥️ Windows setup guide](/documentation/installation_windows.md)\n   - [🔐 Default Accounts](#-default-accounts)\n   - [⚙️ Configuration](#%EF%B8%8F-configuration)\n7. [🤝 Contributing](#-contributing)\n   - [📝 How to Contribute](#-how-to-contribute)\n   - [🔍 Code Style](#-code-style)\n   - [🛠️ Reporting Bugs](#%EF%B8%8F-reporting-bugs)\n   - [💬 Discussion](#-discussion)\n   - [🧑‍💻 Code of Conduct](#-code-of-conduct)\n\n## 🚀 Core Features\n### **Effortless Deployment**  \n_From zero to production in minutes_  \n- 🐳 Docker Compose stack with pre-configured services  \n- 20-minute setup timeline with `docker-compose up` simplicity  \n\n### **Developer-First API Experience**  \n_Spec-driven development workflow_  \n- Auto-generated OpenAPI 3.1 specifications  \n- Interactive Swagger UI endpoint at `/docs`  \n```rust\n// Endpoint registration example\n.route(\"/docs\", get(serve_swagger_ui))\n```\n\n### **Enterprise-Grade Security**  \n_Security by design architecture_  \n- JWT authentication with Argon2id password hashing (OWASP recommended)  \n- TLS 1.3/HTTP2 via AWS-LC (FIPS 140-3 compliant cryptography)\n- Key rotation \u0026 expiration\n- Role-Based Access Control (RBAC) implementation:  \n```rust\n.layer(middleware::from_fn(|req, next| \n    authorize(req, next, vec![1, 2]) // Admin+Mod roles\n))\n```\n\n### **PostgreSQL Integration**  \n_Relational data made simple_  \n- SQLx-powered async database operations  \n- Migration system with transactional safety  \n- Connection pooling for high concurrency  \n\n### **Performance Optimizations**  \n_Engineered for speed at scale_  \n- Brotli compression (11-level optimization)  \n- Intelligent request caching strategies  \n- Zero-copy deserialization pipelines  \n\n### **Operational Visibility**  \n_Production monitoring made easy_  \n- Docker-healthcheck compatible endpoint:  \n```json\n{\n  \"status\": \"degraded\",\n  \"details\": {\n    \"database\": {\"status\": \"ok\"},\n    \"memory\": {\"available_mb\": 21613, \"status\": \"normal\"},\n    \"cpu_usage\": {\"available_percentage\": \"9.85\", \"status\": \"low\"}, \n    \"disk_usage\": {\"used_percentage\": \"74.00\", \"status\": \"ok\"}\n  }\n}\n```\n\n### **Developer Ergonomics**  \n_Code with confidence_  \n- Context-aware user injection system:  \n```rust\nasync fn create_todo(\n    Extension(User { id, role, .. }): Extension\u003cUser\u003e, // Auto-injected\n    Json(payload): Json\u003cTodoRequest\u003e\n) -\u003e Result\u003cimpl IntoResponse\u003e {\n    // Business logic with direct user context\n}\n```\n- Structured logging with OpenTelemetry integration  \n- Compile-time configuration validation  \n\n### **Maintenance \u0026 Compliance**  \n_Future-proof codebase management_  \n- Security-focused dependency tree (cargo-audit compliant)  \n- Comprehensive inline documentation:  \n```rust\n/// JWT middleware - Validates Authorization header\n/// # Arguments\n/// * `req` - Incoming request\n/// * `next` - Next middleware layer\n/// # Security\n/// - Validates Bearer token format\n/// - Checks token expiration\n/// - Verifies cryptographic signature\n```\n\n## 🛠️ Technology stack\n| Category              | Key Technologies               |\n|-----------------------|---------------------------------|\n| Web Framework         | Axum 0.8 + Tower               |\n| Database              | PostgreSQL + SQLx 0.8          |\n| Security              | JWT + Argon2 + Rustls           |\n| Monitoring            | Tracing + Sysinfo              |\n\n## 📂 Project structure\n```\naxium/                              # Root project directory\n├── 📁 migrations/                  # Database schema migrations (SQLx)\n│\n├── 📁 src/                         # Application source code\n│   ├── 📁 core/                    # Core application infrastructure\n│   │   ├── config.rs               # Configuration loader (.env, env vars)\n│   │   └── server.rs               # HTTP/HTTPS server initialization\n│   │\n│   ├── 📁 database/                # Database access layer\n│   │   ├── connection.rs           # Connection pool management\n│   │   ├── queries/                # SQL query modules\n│   │   └── models.rs               # Database entity definitions\n│   │\n│   ├── 📁 middlewares/             # Axum middleware components\n│   ├── 📁 routes/                  # API endpoint routing\n│   │   └── mod.rs                  # Route aggregator\n│   │\n│   ├── 📁 handlers/                # Request handlers\n│   │\n│   ├── 📁 utils/                   # Common utilities\n│   │\n│   └── main.rs                     # Application entry point\n│\n├── 📄 .env                         # Environment configuration\n├── 📄 .env.example                 # Environment template\n├── 📄 Dockerfile                   # Production container build\n├── 📄 docker-compose.yml           # Local development stack\n└── 📄 Cargo.toml                   # Rust dependencies \u0026 metadata\n```\n\nEach folder has a detailed README.md file which explains the folder in more detail.\n\n## 🌐 Default API endpoints\n\n| Method | Endpoint               | Auth Required | Administrator only | Description                          |\n|--------|------------------------|---------------|-------------------|--------------------------------------|\n| POST   | `/signin`              | 🚫            | 🚫                | Authenticate user and get JWT token  |\n| GET    | `/protected`           | ✅            | 🚫                | Test endpoint for authenticated users |\n| GET    | `/health`              | 🚫            | 🚫                | System health check with metrics     |\n|        |                        |               |                   |                                      |\n| **Apikey routes**         |                        |               |                   |                                      |\n| GET    | `/apikeys/all`         | ✅            | 🚫                | Get all apikeys of the current user. |\n| POST   | `/apikeys/`            | ✅            | 🚫                | Create a new apikey.                 |\n| GET    | `/apikeys/{id}`        | ✅            | 🚫                | Get an apikey by ID.                 |\n| DELETE | `/apikeys/{id}`        | ✅            | 🚫                | Delete an apikey by ID.              |\n| POST   | `/apikeys/rotate/{id}` | ✅            | 🚫                | Rotates an API key, disables the old one (grace period 24 hours), returns a new one. |\n|        |                        |               |                   |                                      |\n| **User routes**           |                        |               |                   |                                      |\n| GET    | `/users/all`           | ✅            | ✅                | Get all users.                       |\n| POST   | `/users/`              | ✅            | ✅                | Create a new user.                   |\n| GET    | `/users/{id}`          | ✅            | ✅                | Get a user by ID.                    |\n| DELETE | `/users/{id}`          | ✅            | ✅                | Delete a user by ID.                 |\n|        |                        |               |                   |                                      |\n| **Usage routes**           |                        |               |                   |                                      |\n| GET    | `/usage/lastweek`           | ✅            | 🚫                | Amount of API calls withim the last week of the current user.   |\n| GET   | `/usage/lastday`              | ✅            | 🚫                | Amount of API calls within last day of the current user.                   |\n| | | | | |\n| **Todo routes**           |                        |               |                   |                                      |\n| GET    | `/todos/all`           | ✅            | 🚫                | Get all todos of the current user.   |\n| POST   | `/todos/`              | ✅            | 🚫                | Create a new todo.                   |\n| GET    | `/todos/{id}`          | ✅            | 🚫                | Get a todo by ID.                    |\n| DELETE | `/todos/{id}`          | ✅            | 🚫                | Delete a todo by ID.                 |\n\n## 📦 Installation \u0026 usage\nTo get started with Axium, you'll need to install it on your system. We provide detailed installation guides for different environments:\n\n- **Docker setup**: Follow the instructions in [Docker setup guide](/documentation/installation_docker.md) to run Axium using Docker Compose.\n- **Ubuntu setup**: For users on Ubuntu or other Debian-based systems, refer to the [Ubuntu setup Guide](/documentation/installation_ubuntu.md).\n- **Windows setup**: Windows users can find their setup instructions in the [Windows setup guide](/documentation/installation_windows.md).\n\nThese guides cover cloning the repository, setting up the environment, configuring the database, and running the application.\n\n### 🔐 Default accounts\n\n**Warning:** These accounts should only be used for initial testing. Always change or disable them in production environments.\n\n| Email               | Password | Role           |\n|---------------------|----------|----------------|\n| `user@test.com`     | `test`   | User           |\n| `admin@test.com`    | `test`   | Administrator  |\n\n⚠️ **Security recommendations:**\n1. Rotate passwords immediately after initial setup.\n2. Disable default accounts before deploying to production.\n3. Implement proper user management endpoints.\n\n#### Administrative password resets  \n*For emergency access recovery only*  \n\n1. **Database Access**  \n   Connect to PostgreSQL using privileged credentials:  \n   ```bash  \n   psql -U admin_user -d axium_db -h localhost  \n   ```\n\n2. **Secure Hash Generation**  \n   Use the integrated CLI tool (never user online generators):  \n   ```bash  \n   cargo run --bin argon2-cli -- \"new_password\"  \n   # Output: $argon2id$v=19$m=19456,t=2,p=1$b2JqZWN0X2lkXzEyMzQ1$R7Zx7Y4W...\n   ```\n\n3. **Database Update**  \n   ```sql  \n   UPDATE users  \n   SET \n       password_hash = '$argon2id...',  \n       updated_at = NOW()  \n   WHERE email = 'user@example.com';  \n   ```\n\n4. **Verification**  \n   - Immediately test new credentials  \n   - Force user password change on next login  \n\n### ⚙️ Configuration\nCreate a .env file in the root of the project or configure the application using environment variables.\n\nMake sure to change the `JWT_SECRET_KEY`.\n\n```env\n# ==============================\n# ⚙️ GENERAL CONFIGURATION\n# ==============================\nENVIRONMENT=\"development\" # \"production\"\n\n# ==============================\n# 🌍 SERVER CONFIGURATION\n# ==============================\n\n# IP address the server will bind to (0.0.0.0 allows all network interfaces)\nSERVER_IP=\"0.0.0.0\"\n\n# Port the server will listen on\nSERVER_PORT=\"3000\"\n\n# Enable tracing for debugging/logging (true/false)\nSERVER_TRACE_ENABLED=true\n\n# Amount of threads used to run the server\nSERVER_WORKER_THREADS=2\n\n\n# ==============================\n# 🛢️ DATABASE CONFIGURATION\n# ==============================\n\n# PostgreSQL connection URL (format: postgres://user:password@host/database)\nDATABASE_URL=\"postgres://postgres:1234@localhost/database_name\"\n\n# Maximum number of connections in the database pool\nDATABASE_MAX_CONNECTIONS=20\n\n# Minimum number of connections in the database pool\nDATABASE_MIN_CONNECTIONS=5\n\n\n# ==============================\n# 🔒 HTTPS CONFIGURATION\n# ==============================\n\n# Enable HTTPS (true/false)\nSERVER_HTTPS_ENABLED=false\n\n# Enable HTTP/2 when using HTTPS (true/false)\nSERVER_HTTPS_HTTP2_ENABLED=true\n\n# Path to the SSL certificate file (only used if SERVER_HTTPS_ENABLED=true)\nSERVER_HTTPS_CERT_FILE_PATH=cert.pem\n\n# Path to the SSL private key file (only used if SERVER_HTTPS_ENABLED=true)\nSERVER_HTTPS_KEY_FILE_PATH=key.pem\n\n\n# ==============================\n# 🚦 RATE LIMIT CONFIGURATION\n# ==============================\n\n# Maximum number of requests allowed per period\nSERVER_RATE_LIMIT=5\n\n# Time period (in seconds) for rate limiting\nSERVER_RATE_LIMIT_PERIOD=1\n\n\n# ==============================\n# 📦 COMPRESSION CONFIGURATION\n# ==============================\n\n# Enable Brotli compression (true/false)\nSERVER_COMPRESSION_ENABLED=true\n\n# Compression level (valid range: 0-11, where 11 is the highest compression)\nSERVER_COMPRESSION_LEVEL=6\n\n\n# ==============================\n# 🔑 AUTHENTICATION CONFIGURATION\n# ==============================\n\n# JWT secret key.\nJWT_SECRET_KEY=\"Change me!\"\n```\n\n## 🤝 Contributing\n\nWe 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.\n\n### 📝 How to Contribute\n\n1. **Fork the Repository**  \n   Start by forking the repository to your own GitHub account.\n\n2. **Clone Your Fork**  \n   Clone your forked repository to your local machine:\n   ```bash\n   git clone https://github.com/your-username/Axium.git\n   cd Axium\n   ```\n\n3. **Create a New Branch**  \n   Create a new branch for your feature or bug fix:\n   ```bash\n   git checkout -b feature-name\n   ```\n\n4. **Make Your Changes**  \n   Make the necessary changes to the code or documentation. Make sure to write tests for new features and adhere to the existing code style.\n\n5. **Commit Your Changes**  \n   Commit your changes with a clear, descriptive message:\n   ```bash\n   git commit -m \"Add feature XYZ or fix issue ABC\"\n   ```\n\n6. **Push to Your Fork**  \n   Push your changes to your fork:\n   ```bash\n   git push origin feature-name\n   ```\n\n7. **Open a Pull Request**  \n   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.\n\n### 🔍 Code Style\n\n- Follow the **Rust style guidelines** outlined in the [Rust Style Guide](https://doc.rust-lang.org/1.0.0/style/).\n- Use **cargo fmt** to automatically format your code:\n  ```bash\n  cargo fmt\n  ```\n- Write **meaningful commit messages** that describe the changes you've made.\n\n### 🛠️ Reporting Bugs\n\nIf 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:\n\n- A clear description of the problem.\n- Steps to reproduce the issue.\n- Expected vs. actual behavior.\n- Any relevant logs or error messages.\n\n### 💬 Discussion\n\nFeel 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.\n\n### 🧑‍💻 Code of Conduct\n\nPlease 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.\n\n### 🎉 Thanks for Contributing!\n\nYour contributions help make Axium better for everyone! 🙏\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friktastic%2Faxium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friktastic%2Faxium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friktastic%2Faxium/lists"}