Quick Start Guide

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 C++ library that provides a complete backend solution. Create database tables and instantly get REST APIs, authentication, file handling, and an admin dashboard - all in a single lightweight binary.

Key Features:

• Auto-generated REST APIs for all your data
• Built-in JWT authentication
• Access control with flexible rules
• Admin dashboard for data management
• File upload and serving
• JavaScript extensions for custom logic
• Embeddable in your C++ applications

---

Installation

Quick Start (Pre-built Binaries)

1. Download the latest release from GitHub Releases
2. Extract the zip file
3. Run the server:

./mantisbase serve

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

Linux Dependencies:

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

Build from Source

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

See Installation Guide for more details.

---

First Steps

1. Create an Admin Account

Before using the admin dashboard, create an admin user:

./mantisbase admins --add admin@example.com admin_password_bjb12!

2. Access the Admin Dashboard

Open your browser and go to:

http://localhost:7070/mb

Log in with the admin credentials you just created.

The Admin Dashboard is a powerful visual interface that provides:

• Visual Data Management - Browse, create, edit, and delete records through an intuitive table interface
• Schema Builder - Create and configure entity schemas without writing API calls
• Access Control Configuration - Set up access rules with a user-friendly interface
• Search & Filtering - Quickly find records with built-in search and filter capabilities
• File Management - Upload and manage files associated with your entities

The dashboard is the recommended way to interact with MantisBase during development, as it provides a complete GUI alternative to the REST API and makes it easy to explore and manage your data.

3. Create Your First Entity

You can create entities (tables) via the admin dashboard or using the API:

Using the Admin Dashboard (Recommended):

1. Log in to the admin dashboard at http://localhost:7070/mb
2. Navigate to "Schemas" or use the sidebar to access entity management
3. Click "New" or "Create New"
4. Define your table name, fields, and access rules using the visual interface
5. The dashboard will automatically generate the API endpoints for your new entity

Using the API:

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"},
      {"name": "author_id", "type": "string", "required": true}
    ],
    "rules": {
      "list": {"mode": "public", "expr": ""},
      "get": {"mode": "public", "expr": ""},
      "add": {"mode": "auth", "expr": ""},
      "update": {"mode": "custom", "expr": "auth.id == req.body.author_id"},
      "delete": {"mode": "", "expr": ""}
    }
  }'

Entity Types:

• **base** - Standard database table with fields (most common)
• **auth** - Authentication entity with built-in password and user management
• **view** - SQL view based on a query (read-only, requires view_query instead of fields)

Entity Name Rules:

• Must be alphanumeric characters and underscores only (a-z, A-Z, 0-9, _)
• Maximum 64 characters
• Names are automatically validated to prevent SQL injection

4. Use Your Auto-generated API

Once created, your entity automatically has REST endpoints:

# List all posts
curl http://localhost:7070/api/v1/entities/posts
 
# Get a specific post
curl http://localhost:7070/api/v1/entities/posts/<id>
 
# 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!", "author_id": "user123"}'
 
# 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>"

---

Authentication

User Login

MantisBase provides standalone authentication endpoints:

# 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": "eyJhbGc...", "user": {...}}

Using Tokens

Include the token in all authenticated requests:

curl -H "Authorization: Bearer <token>" \
  http://localhost:7070/api/v1/entities/posts

See Authentication API for all auth endpoints.

---

Access Control

Each entity can define access rules for each operation:

• **public** - Open to everyone
• **auth** - Any authenticated user
• Empty mode - Admin only
• **custom** - JavaScript expression evaluation

Example rules:

{
  "rules": {
    "list": {"mode": "public", "expr": ""},
    "get": {"mode": "public", "expr": ""},
    "add": {"mode": "auth", "expr": ""},
    "update": {"mode": "custom", "expr": "auth.id == req.body.author_id"},
    "delete": {"mode": "", "expr": ""}
  }
}

See Access Rules for detailed documentation.

---

File Handling

Upload files using multipart/form-data:

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

Access files at:

http://localhost:7070/api/files/posts/photo.jpg

See File Handling for details.

---

API Endpoints Overview

Entity Endpoints

All entities automatically get these 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 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

Schema Management (Admin Only)

• GET /api/v1/schemas - List all schemas
• GET /api/v1/schemas/:id - Get schema
• POST /api/v1/schemas - Create schema
• PATCH /api/v1/schemas/:id - Update schema
• DELETE /api/v1/schemas/:id - Delete schema

System Endpoints

• GET /api/v1/health - Health check
• GET /api/v1/sys/logs - System logs (admin only, see API Reference)
• GET /api/files/<entity>/<filename> - Serve files
• GET /mb - Admin dashboard

See API Reference for complete documentation.

---

Configuration

Command-Line Options

# Custom port and host
mantisbase serve --port 8080 --host 0.0.0.0
 
# Development mode
mantisbase --dev serve
 
# PostgreSQL database
mantisbase --database PSQL \
  --connection "dbname=mantis host=localhost user=postgres password=pass" \
  serve
 
# Custom directories
mantisbase --dataDir ./data --publicDir ./public --scriptsDir ./scripts serve

Environment Variables

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

See CLI Reference for all options.

---

Next Steps

Now that you have MantisBase running:

1. Explore the Admin Dashboard - Create tables, manage data, and configure access rules
2. Read the API Documentation - Learn about all available endpoints
3. Set Up Access Rules - Configure who can access what
4. Try File Uploads - Upload and serve files
5. Add Custom Endpoints - Extend functionality with JavaScript or C++
6. Embed in Your App - Use MantisBase as a library in your C++ project

---

Documentation

• Installation Guide - Detailed installation instructions
• CLI Reference - All command-line options
• API Reference - Complete API documentation
• Authentication API - Auth endpoints and usage
• Access Rules - Permission system guide
• Embedding Guide - Use as a C++ library
• File Handling - File upload and serving
• Scripting Guide - JavaScript extensions
• Docker Guide - Running in containers

---

Common Use Cases

Desktop Application Backend

Embed MantisBase in your Qt, Slint, or native C++ desktop app to provide local data storage and REST APIs.

Development Server

Use MantisBase as a quick backend for frontend development, prototyping, or testing.

Embedded Device

Run MantisBase on embedded devices to provide a local API server with data persistence.

Microservice

Deploy MantisBase as a standalone microservice for specific data management needs.

---

Getting Help

• Documentation: Check the docs directory for detailed guides
• Issues: Report bugs or request features on GitHub Issues
• Examples: See the examples directory for code samples

---

Summary

MantisBase provides everything you need for a backend in a single C++ library:

• Create tables and get instant REST APIs
• Built-in authentication and access control
• Admin dashboard for easy management
• File handling and JavaScript extensions
• Embeddable in your applications

Get started in minutes, scale as needed.