allankoech/mantisbase repository overview

⁠MantisBase

MantisBase is a self-hosted Backend-as-a-Service written in C++20. A single binary gives you instant REST APIs, JWT authentication, realtime SSE and WebSocket streams, file uploads, and a web admin dashboard — with no runtime dependencies.

• Source: github.com/allankoechke/mantisbase⁠
• Documentation: docs.mantisbase.com⁠

⁠Quick start

docker run -d --name mantisbase -p 7070:8080 allankoech/mantisbase

The server listens on port 8080 inside the container. Map it to any host port you like.

⁠Persistent data

A container restart discards everything unless you mount volumes. Four directories are relevant:

docker run -d --name mantisbase -p 7070:8080 \
  -e MB_JWT_SECRET=change-me \
  -v $(pwd)/data:/mb/data \
  -v $(pwd)/www:/mb/public \
  -v $(pwd)/scripts:/mb/scripts \
  -v $(pwd)/migrations:/mb/migrations \
  allankoech/mantisbase

⁠Create an admin account

On first boot, open http://localhost:7070/mb and create the admin account through the dashboard. To create one from the CLI instead:

docker exec -it mantisbase /mb/mantisbase admins --add [email protected] 'your-strong-password'

Set MB_DEFAULT_ADMIN_EMAIL and MB_DEFAULT_ADMIN_PASSWORD to run admins --add without arguments, or set MB_SKIP_ADMIN_SETUP=1 to skip the first-boot setup prompt entirely.

⁠Docker Compose

services:
  mantisbase:
    image: allankoech/mantisbase:latest
    restart: unless-stopped
    ports:
      - "7070:8080"
    volumes:
      - ./data:/mb/data
      - ./www:/mb/public
      - ./scripts:/mb/scripts
      - ./migrations:/mb/migrations
    environment:
      MB_JWT_SECRET: ${MB_JWT_SECRET:-}

docker compose up -d

⁠Configuration

All environment variables use the MB_ prefix. When a variable is set, it overrides the matching CLI option.

⁠Passing CLI arguments

The image entrypoint is /mb/mantisbase and the default command is serve -p 80. Anything you append after the image name replaces that default command, so include serve -p 80 yourself:

# Verbose development logging
docker run -p 7070:80 allankoech/mantisbase --dev serve -p 80

Global options such as --db and --db_url must come before the serve subcommand:

docker run -d -p 7070:80 \
  -e MB_JWT_SECRET=change-me \
  allankoech/mantisbase \
  --db postgresql \
  --db_url "dbname=mantis host=postgres port=5432 user=postgres password=postgres" \
  serve -p 80

See the CLI reference⁠ for every flag.

⁠Features

• Auto-generated REST APIs — create an entity, get CRUD endpoints instantly
• JWT authentication — login, refresh, logout, API keys, and OAuth providers
• Access control rules — public, auth, or custom expression-based permissions per operation
• Realtime — SSE at /api/v1/realtime and WebSocket at /api/v1/realtime/ws
• File handling — multipart uploads tied to entity records, served from /api/v1/files/<entity>/<filename>
• Admin dashboard — manage schemas, records, users, files, and logs from the browser
• JavaScript extensions — add custom routes and logic without recompiling
• SQLite and PostgreSQL — both backends support realtime change streams

⁠Tags

Published images are linux/amd64 only. The Dockerfile⁠ also supports arm64 — build it yourself with docker build --platform linux/arm64.

The image is based on debian:stable-slim and is roughly 40 MB compressed.

⁠Health check

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:80/api/v1/health || exit 1

livenessProbe:
  httpGet:
    path: /api/v1/health
    port: 80
  initialDelaySeconds: 30
  periodSeconds: 10

A healthy server returns 200 OK with {"status": "OK"}.

⁠Examples

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

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

# Upload a file with a record
curl -X POST http://localhost:7070/api/v1/entities/posts \
  -H "Authorization: Bearer <token>" \
  -F "title=My Post" \
  -F "[email protected]"

⁠Documentation and support

• Documentation⁠
• API reference⁠
• Docker guide⁠
• Issues⁠
• Discussions⁠

⁠License

MIT © 2025 Allan K. Koech