A lightweight, pluggable Backend-as-a-Service (BaaS) library built in C++
Portable. Embeddable. Built for speed and extensibility.

---

What is MantisBase?

MantisBase is a lightweight C++ library that provides a complete backend solution with:

• Auto-generated REST APIs - Create database tables and get instant REST endpoints
• Built-in Authentication - JWT-based auth with access control rules
• Admin Dashboard - Web interface for managing your data
• File Uploads - Handle file storage and serving
• JavaScript Extensions - Extend functionality with scripts
• Embeddable - Use as a library in your C++ applications

Perfect for embedded devices, desktop apps, or standalone servers.

---

Quick Start

1. Download and Run

Download the latest release from GitHub Releases, extract it, and run:

./mantisbase serve

The server starts on http://localhost:7070 with:

• API endpoints at http://localhost:7070/api/v1/
• Admin dashboard at http://localhost:7070/mb

2. Create Admin Account

Before using the admin dashboard, create an admin user:

./mantisbase admins add admin@example.com very_string_password_123!@h

Once admin user has been created, log in at http://localhost:7070/mb.

Admin Dashboard

MantisBase includes a powerful web-based admin dashboard that provides a visual interface for managing your data. The dashboard is essential for:

• Visual Data Management - View, create, edit, and delete records through an intuitive interface
• Schema Management - Create and configure entity schemas without writing API calls
• Access Control Configuration - Set up access rules visually
• Real-time Data Exploration - Browse your data with search, filtering, and pagination
• User Management - Manage authentication entities and users

Access the dashboard at http://localhost:7070/mb after creating an admin account. The dashboard provides a complete GUI alternative to the REST API, making it perfect for non-technical users and rapid development.

3. Create Your First Entity

Use the admin dashboard or API to create a table. For example, create a posts table:

curl -X POST http://localhost:7070/api/v1/schemas \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "posts",
    "type": "base",
    "fields": [
      {"name": "title", "type": "string", "required": true},
      {"name": "content", "type": "string"}
    ],
    "rules": {
      "list": {"mode": "public", "expr": ""},
      "get": {"mode": "public", "expr": ""},
      "add": {"mode": "auth", "expr": ""},
      "update": {"mode": "auth", "expr": ""},
      "delete": {"mode": "", "expr": ""}
    }
  }'

Entity Name Rules:

• Entity names must be alphanumeric characters and underscores only
• Maximum length: 64 characters
• Names are validated automatically to prevent SQL injection

Entity Types:

• base - Standard database table with fields
• auth - Authentication entity with built-in password and user management fields
• view - SQL view based on a query (read-only, no fields)

4. Use Your API

Once created, your entity automatically gets REST endpoints:

# List all posts
curl http://localhost:7070/api/v1/entities/posts

# Create a post (requires authentication)
curl -X POST http://localhost:7070/api/v1/entities/posts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "My First Post", "content": "Hello World!"}'

# Get a specific post
curl http://localhost:7070/api/v1/entities/posts/<id>

# Update a post
curl -X PATCH http://localhost:7070/api/v1/entities/posts/<id> \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'

# Delete a post
curl -X DELETE http://localhost:7070/api/v1/entities/posts/<id> \
  -H "Authorization: Bearer <token>"

That's it! You now have a fully functional backend with authentication and access control.

---

Installation Options

Option 1: Pre-built Binaries (Recommended for Beginners)

1. Download from GitHub Releases
2. Extract the zip file
3. Run ./mantisbase serve

Option 2: Build from Source

Dependencies (Linux only):

sudo apt-get install -y libzstd-dev libpq-dev

git clone --recurse-submodules https://github.com/allankoechke/mantisbase.git
cd mantisbase
cmake -B build
cmake --build build
./build/mantisbase serve

Option 3: Embed in Your Project

Add MantisBase as a submodule and link it in your CMake project:

#include <mantisbase/mantisbase.h>

int main(int argc, char* argv[])
{
    auto& app = mb::MantisBase::create(argc, argv);
    return app.run();
}

See Embedding Guide for details.

Option 4: Docker

docker build -t mantisbase -f docker/Dockerfile .
docker run -p 7070:80 mantisbase

See Docker Guide for details.

---

Key Features

Admin Dashboard

The MantisBase Admin Dashboard is a fully-featured web interface that provides visual management of your entire backend:

• Entity Management - Create, view, edit, and delete records through an intuitive table interface
• Schema Builder - Design database schemas with a visual form builder
• Access Rules Editor - Configure permissions with a user-friendly interface
• File Management - Upload and manage files associated with your entities
• Search & Filtering - Quickly find and filter records across all entities
• Real-time Updates - See changes reflected immediately

The dashboard is accessible at /mb and requires admin authentication. It's the recommended way to interact with MantisBase during development and for non-technical team members.

Auto-generated REST APIs

Every entity (table) you create automatically gets REST endpoints:

• GET /api/v1/entities/<entity> - List records
• GET /api/v1/entities/<entity>/:id - Get record
• POST /api/v1/entities/<entity> - Create record
• PATCH /api/v1/entities/<entity>/:id - Update record
• DELETE /api/v1/entities/<entity>/:id - Delete record

Authentication

Standalone authentication endpoints:

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/refresh - Refresh token
• POST /api/v1/auth/logout - Logout
• POST /api/v1/auth/setup/admin - Create initial admin

See Authentication API for details.

System Endpoints

• GET /api/v1/health - Health check
• GET /api/v1/sys/logs - System logs with filtering and pagination (admin only)

Access Control

Define who can access what using simple rules:

{
  "rules": {
    "list": {"mode": "public", "expr": ""},      // Public access
    "get": {"mode": "auth", "expr": ""},         // Any authenticated user
    "add": {"mode": "custom", "expr": "auth.user.verified == true"},  // Custom condition
    "update": {"mode": "", "expr": ""},          // Admin only
    "delete": {"mode": "", "expr": ""}           // Admin only
  }
}

See Access Rules for details.

File Handling

Upload and serve files with multipart/form-data:

# Upload file when creating record
curl -X POST http://localhost:7070/api/v1/entities/posts \
  -H "Authorization: Bearer <token>" \
  -F "title=My Post" \
  -F "image=@photo.jpg"

# Access file
curl http://localhost:7070/api/files/posts/photo.jpg

See File Handling for details.

JavaScript Extensions

Caution

CURRENTLY, SCRIPTING IS DISABLED UNTIL v0.3.x API IS STABLIZED!!!

Extend functionality with JavaScript scripts:

app.router().addRoute("GET", "/api/v1/custom", function(req, res) {
    res.json(200, {message: "Custom endpoint"});
});

See Scripting Guide for details.

---

Configuration

Command-Line Options

# Start server on custom port
mantisbase serve --port 8080 --host 0.0.0.0

# Use PostgreSQL
mantisbase --database PSQL \
  --connection "dbname=mantis host=localhost user=postgres password=pass" \
  serve

# Development mode (verbose logging)
mantisbase --dev serve

# Custom directories
mantisbase --dataDir ./my-data --publicDir ./my-public serve

See CLI Reference for all options.

Environment Variables

# Set JWT secret (important for production)
export MANTIS_JWT_SECRET=your-secret-key-here

---

Project Structure

mantisbase/
├── include/mantisbase/  # Public API headers
├── src/                 # Implementation
├── examples/            # Example projects
├── tests/               # Test suite
├── docker/              # Docker files
└── doc/                 # Documentation

---

Documentation

• Quick Start Guide - Get started quickly
• CLI Reference - Command-line options
• API Reference - REST API documentation
• Authentication API - Auth endpoints
• Access Rules - Permission system
• Embedding Guide - Use as a library
• File Handling - File uploads
• Scripting Guide - JavaScript extensions

For full API documentation, visit https://docs.mantisbase.dev.

---

Tech Stack

• Language: C++20
• Database: SQLite (default), PostgreSQL (Linux)
• Build System: CMake
• HTTP Server: httplib-cpp
• JavaScript Engine: Duktape
• Dependencies: All included as submodules

Note: On Windows, use MinGW (v13+) instead of MSVC due to feature compatibility.

---

Requirements

• Linux: GCC with C++20 support, libzstd-dev, libpq-dev (for PostgreSQL)
• Windows: MinGW v13+ with std::format support
• No external runtime dependencies - everything is bundled

---

Examples

Create and Query Data

# 1. Create a schema
curl -X POST http://localhost:7070/api/v1/schemas \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "users", "type": "base", "fields": [{"name": "name", "type": "string"}]}'

# 2. Create a record
curl -X POST http://localhost:7070/api/v1/entities/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe"}'

# 3. List records
curl http://localhost:7070/api/v1/entities/users

Authentication Flow

# 1. Login (identity can be email or user ID)
curl -X POST http://localhost:7070/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"entity": "users", "identity": "user@example.com", "password": "password"}'

# Response: {"token": "...", "user": {...}}

# 2. Use token in requests
curl -H "Authorization: Bearer <token>" \
  http://localhost:7070/api/v1/entities/posts

---

Status

MantisBase is under active development. The API may change as the project stabilizes. Follow the v0.3 branch for upcoming changes.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

---

License

MIT License © 2025 Allan K. Koech

---

Resources

• GitHub Repository
• Documentation
• YouTube Playlist