Introduction

MangoPanel is a lightweight, self-hosted, hPanel-style shared hosting control panel. It provides a complete web hosting control plane designed for real account stacks, queued jobs, DNS management, SSL certificates, email services, databases, file managers, and backups.

Key Platform Highlights

• Account Isolation: One dedicated Docker Compose stack per customer account (OpenLiteSpeed, MariaDB, phpMyAdmin, Filebrowser, SFTP, Mail).
• Audited Control Plane: Single SQLite database (`mangopanel.sqlite3`) tracking users, websites, databases, mailboxes, and job logs.
• Built-in Security: Signed JWT session tokens, mandatory TOTP multi-factor authentication, and short-lived launch tokens for sub-services.
• Dual-Port Panel Architecture: Separate listening ports for Client (`8000`) and Admin (`8001`) to isolate administrative API routes.

Requirements

Before installing MangoPanel, ensure your server or development environment satisfies the following system specifications:

Installation

Choose one of the following methods to install MangoPanel on your host system.

Option A: Automated One-Line Install (Recommended)

Fresh clone and auto-installation using `git`:

git clone https://github.com/servermango/MangoPanel.git MangoPanel && cd MangoPanel && bash scripts/install.sh

Option B: Archive Install (If Git is unavailable)

mkdir MangoPanel && curl -fsSL https://codeload.github.com/servermango/MangoPanel/tar.gz/refs/heads/main | tar -xz -C MangoPanel --strip-components=1 && cd MangoPanel && bash scripts/install.sh

Option C: Manual Makefile Step-by-Step

cd MangoPanel

# 1. Install system prerequisites, Python venv, Docker tools & pre-pull images
make install

# 2. Check Python, Docker, and listening ports
make dev-init

# 3. Start the client and admin panel services (seeds dev data on first run)
make dev-up

Quick Start

Once installation finishes, MangoPanel runs as a local background daemon or development server.

Basic Setup

Follow these steps to configure your initial administrative credentials, define hosting plans, and provision your first customer accounts.

1. Admin Setup & Recovery

When starting MangoPanel on a fresh database with zero admins, visiting `http://:8001/admin` automatically routes to the First-Admin Setup Page (`/admin/setup`).

• Fill in the admin email address and password.
• The system generates an initial TOTP authenticator secret and displays an `otpauth://` QR code.
• Scan the QR code in Google Authenticator / 1Password and verify a code before completing setup.
• Once an admin exists, public first-admin setup is permanently locked.

CLI Admin Recovery Tool

If an administrator loses password or 2FA access, run `scripts/admin_recovery.py` directly on the server host:

# Reset admin password
sudo python3 scripts/admin_recovery.py --email [email protected] --set-password

# Generate new TOTP secret & display QR setup URI
sudo python3 scripts/admin_recovery.py --email [email protected] --enable-totp

# Disable TOTP requirement for emergency login
sudo python3 scripts/admin_recovery.py --email [email protected] --disable-totp

2. Creating Hosting Plans

Before customer accounts can be provisioned, define at least one active Hosting Plan in the Admin Panel under Plans (`/admin#plans`).

3. Provisioning Customer Clients

Customer accounts can be created through two primary workflows:

Workflow A: Self-Service Signup Page (`/signup`)

1. User visits `http://:8000/signup`.
2. Enters email, password, and selects an available hosting plan.
3. API executes `POST /api/public/signup`, generates customer credentials, sets up 2FA, and assigns an account ID (e.g., `u000001`).

Workflow B: Admin Dashboard Provisioning

1. Admin opens Admin Panel > Clients.
2. Clicks Create Client Account.
3. Enters user email, password, and selects the hosting plan.
4. The system creates the user, generates account directory structure under `user_files/accounts//`, and queues container deployment.

Cloudflare as DNS - Setup Instructions

MangoPanel supports Cloudflare as an authoritative DNS provider for managed domains. Configure Cloudflare credentials in the Admin panel under DNS Settings.

Cloudflare API Prerequisites

• Account ID: Found in the right sidebar of the Cloudflare Dashboard on any domain's Overview page.
• API Token: Generated under My Profile > API Tokens in Cloudflare.

Automated ACME Challenge Page Rules

When a website is added or connected to MangoPanel using Cloudflare DNS, MangoPanel automatically creates a Cloudflare Page Rule targeting http://*example.com/.well-known/acme-challenge/* with action always_use_https: off. This prevents Cloudflare from redirecting Let's Encrypt HTTP ACME challenges to HTTPS port 443 before Caddy has issued an SSL certificate, eliminating HTTP 525 (SSL Handshake Failed) deadlocks.

Syncing Existing Websites

To add missing Cloudflare Page Rules to existing websites, you can use any of the following methods:

• API Endpoint (Client Area): POST /api/client/dns/sync-cloudflare-rules
• API Endpoint (Admin Area): POST /api/admin/dns/sync-cloudflare-rules
• CLI Script: Run python scripts/sync_cloudflare_rules.py on your server

Domain & Subdomain DNS Setup

To instruct users to set up a server domain or subdomain for MangoPanel and tool access, create DNS A-records pointing to your server's IP address.

Once configured, access MangoPanel at:

• Admin Panel: http://hosting.servermango.com:8001/admin
• Client Panel: http://hosting.servermango.com:8000/client (or http://hosting.servermango.com:8000/)

Current Build Features

• Python standard-library HTTP API with zero framework overhead.
• SQLite WAL-mode schema with versioned development seed data.
• Public client signup (`/signup`), client portal (`/`), admin panel (`/admin`), and status page (`/status`).
• Full coverage for websites, MySQL, PostgreSQL, mailboxes, SFTP, cron jobs, backups, Git deployments, and audit logs.
• Node-agent job runner with simulated and Docker Compose execution modes.
• Account-stack generator for OpenLiteSpeed, Filebrowser, phpMyAdmin, MariaDB, cron, SFTP, and shared mail scaffolding.

Service Command

MangoPanel includes a portable service wrapper at scripts/service that manages background panel processes and agent workers without requiring `systemd`:

# Service lifecycle management
bash scripts/service mangopanel start
bash scripts/service mangopanel status
bash scripts/service mangopanel restart
bash scripts/service mangopanel stop

# Makefile wrapper equivalent
make service ACTION=start
make service ACTION=status

cd /root/MangoPanel
sudo systemctl start mangopanel.service
sudo systemctl status mangopanel.service --no-pager

# The service must define:
# MP_ENV=production
# MP_AGENT_MODE=docker

How It Works

Request flow in one line:

Data Layout

All persistent control-plane state and customer hosting data lives under user_files/:

user_files/
  accounts/                 # per-customer hosting files  (MP_ACCOUNT_ROOT)
    u000001/
      account.json
      domains/<domain>/public_html/
      databases/  mail/  backups/  ssl/  git/  .runtime/
  data/                     # control-plane database       (MP_DATA_DIR)
    mangopanel.sqlite3

Server Migration

Because all database state and customer files live inside `user_files/`, migration to a new server takes 5 simple steps:

1. Stop Services: bash scripts/service mangopanel stop on old server.
2. Install on New Server: Run installation script on destination machine.
3. Transfer `user_files/`: rsync -avzP /path/to/old/user_files/ root@new-server:/path/to/new/user_files/
4. Start Services & Provision Stacks: bash scripts/service mangopanel start & run agent stack rebuild.
5. Update DNS: Point A-records to the new server IP.

Local & Docker Development

# Start lightweight dev server (Simulated Mode)
make dev-up

# Start full Docker hosting stack (OpenLiteSpeed, MariaDB, SFTP containers)
make dev-up-docker

# Run unit tests
make test

# Run API smoke test suite
make dev-smoke

Thesis Integration Direction

MangoPanel is evaluated as a case study for Tariq Abdullah's Cloud Definition Language (CDL) M.Tech thesis research, exploring how shared-hosting platform intent can be compiled into explainable infrastructure artifacts.

Implementation Roadmap

• Phase 1 (Implemented): Shared interfaces and control-plane schema.
• Phase 2 (Implemented): Local PowerDNS adapter, ACME provider, and mail edge scaffolding.
• Phase 3 (Implemented): Hardening, auth validation, and client dashboard metrics integration.

# Option A: Bearer Header (Recommended)
Authorization: Bearer mp_YOUR_API_KEY

# Option B: X-API-Key Header
X-API-Key: mp_YOUR_API_KEY

# Option C: Query Parameter
GET /api/client/websites?api_key=mp_YOUR_API_KEY

# Optional: Scope to a specific hosting account (multi-account users)
X-Hosting-Account-ID: 2

# Create a new website
curl -X POST "http://your-server:8000/api/client/websites" \
     -H "Authorization: Bearer mp_YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domain": "mysite.com", "php_version": "8.3"}'

import requests

API_KEY = "mp_YOUR_API_KEY"
BASE_URL = "http://your-server:8000"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Add a new DNS A-record
payload = {
    "domain_id": 1,
    "name": "sub",
    "type": "A",
    "value": "127.0.0.1",
    "ttl": 300,
    "proxied": True
}
res = requests.post(f"{BASE_URL}/api/client/dns-records", headers=headers, json=payload)
print(res.json())

# Bearer header (only supported method for admin tokens)
Authorization: Bearer mp_admin_YOUR_API_KEY

# X-API-Key header also accepted
X-API-Key: mp_admin_YOUR_API_KEY

# Query parameter also accepted
GET /api/admin/dashboard?api_key=mp_admin_YOUR_API_KEY

# Bearer header (recommended)
Authorization: Bearer mp_reseller_YOUR_API_KEY

# X-API-Key header also accepted
X-API-Key: mp_reseller_YOUR_API_KEY

# Query parameter also accepted
GET /api/reseller/dashboard?api_key=mp_reseller_YOUR_API_KEY