🚀 Mycelium: The Ultimate API Gateway

Mycelium is an open and free API Gateway, designed to operate in modern, multi-tenant, and API-oriented environments. The project prioritizes architectural clarity, security, and extensibility, maintaining an explicit separation between technical concerns and organizational aspects of the project.

This repository documents the fundamentals of Mycelium, with special focus on its authorization model, which combines declarative controls at the gateway with contextual decisions close to the resource.

📖 Documentation

📚 View Complete Documentation →

Access the full documentation website with guides, tutorials, and API reference.

Quick Links

📚 Complete Documentation - Full documentation guide

🚀 Installation Guide - Get started with installation

⚡ Quick Start - Up and running in minutes

⚙️ Configuration - Configure Mycelium

🔐 Authorization Model - Deep dive into security

Overview

Mycelium acts as the entry layer for downstream services, being responsible for authentication, identity normalization, routing, and security policy enforcement. The gateway does not impose business logic, but provides authorization primitives that allow each service to evaluate permissions in an explicit, secure, and contextual manner.

The project is maintained as open source software, with its continuity based on governance, community collaboration, and ecosystem funding and acceleration initiatives — aspects that are independent of internal technical decisions.

Key Features

• Modern and extensible API Gateway
• Native support for multi-tenant environments
• Authorization at multiple layers (gateway and downstream)
• Identity context injection via Profile
• Composable authorization primitives
• Architecture compatible with market standards

Authorization Model

Mycelium's authorization model is one of its central pillars and is documented in detail in the file:

👉 Authorization

In summary:

• The gateway applies declarative controls per route (coarse-grained)
• Downstream services apply contextual authorizations (fine-grained)
• The Profile acts as an active capability object, not just as an identity payload

Conceptual Structure

Client
  ↓
API Gateway (auth, routing, edge RBAC)
  ↓
Downstream Services (contextual FBAC)

This separation ensures low coupling, high expressiveness, and security decisions close to the resource.

Project Governance and Sustainability

Mycelium is an open and free project. Its maintenance and evolution are handled within the project's organizational scope, through:

• Community collaboration
• Institutional support
• Funding and acceleration initiatives

These aspects do not influence or condition the technical authorization model, which remains neutral, explicit, and verifiable.

Getting Started

Prerequisites

Before installing Mycelium, ensure you have:

• Rust (version 1.70 or higher) - Install Rust
• Postgres (version 14 or higher) - Database for tenant and user management
• Redis (version 6 or higher) - Caching layer
• HashiCorp Vault (optional) - Recommended for production secret management
• Docker (optional) - For containerized deployment

For detailed system dependencies and installation instructions, see the Installation Guide.

Installation

Install Mycelium using Cargo:

cargo install mycelium-api

Or using Docker:

docker pull sgelias/mycelium-api:latest

For complete installation instructions including database setup and Vault configuration, see the Installation Guide.

Quick Start

1. Initialize the database:

   psql postgres://postgres:postgres@localhost:5432/postgres \
     -f postgres/sql/up.sql \
     -v db_password='your-password'
   

2. Configure Mycelium:

   cp settings/config.example.toml settings/config.toml
   # Edit config.toml with your settings
   

3. Start Mycelium:

   SETTINGS_PATH=settings/config.toml myc-api
   

4. Verify it's running:

   curl http://localhost:8080/health
   

For a complete quick start guide with minimal configuration, see Quick Start Guide.

Running Tests

Execute the test suite:

# Run all tests
cargo test

# Run with coverage
cargo tarpaulin --out Html

# Run specific tests
cargo test auth

For detailed testing instructions including integration tests and benchmarks, see Running Tests.

Documentation

📚 Online Documentation - Browse the complete documentation website

Alternatively, you can access documentation files directly in the docs/book/src/ directory:

• Introduction - Overview and key features
• Installation - Installation and setup
• Quick Start - Get started quickly
• Configuration - Configuration options
• Deploy Locally - Local deployment with Docker
• Authorization Model - Security and authorization
• Downstream APIs - Configure routes and services
• Running Tests - Testing guide

Project Status

Mycelium is under active development and open to contributions. Architectural discussions, improvement proposals, and conceptual reviews are welcome.

Contributing

We welcome contributions! Mycelium is an open-source project and we appreciate:

• 🐛 Bug reports and fixes
• ✨ Feature requests and implementations
• 📝 Documentation improvements
• 🔍 Code reviews
• 💡 Ideas and discussions

Getting Started

1. Read our Contributing Guide for detailed guidelines
2. Check out existing issues or create a new one
3. Fork the repository and create a feature branch
4. Make your changes following our code standards
5. Submit a pull request - our PR template will be automatically loaded

When you create a PR, GitHub automatically loads our pull request template with sections for summary, testing details, and a comprehensive checklist to ensure code quality and proper documentation.

License

See the LICENSE file for details about the project's licensing.