Introduction

modoboa-pro is a Modoboa extension that adds virtual host management to an existing Modoboa installation. It registers itself with the host through Modoboa's extension pool, ships its own database models, REST API and background jobs, and injects a Vue frontend (loaded at runtime by the Modoboa web interface).

The extension does not replace any part of Modoboa — it plugs into the instance you already run.

What is a virtual host?

A virtual host is a public hostname (for example mail.example.com) that:

• is served over HTTPS with its own TLS certificate;
• is backed by a generated Nginx server block that proxies to your Modoboa application;
• can be linked to one or more mail domains managed in Modoboa;
• can carry its own theme (colors and logos) so each tenant gets a branded interface.

This lets a single Modoboa instance present several independent, branded front doors — one per customer, brand or domain — instead of a single shared hostname.

Features at a glance

Feature	Description
Virtual host management	Create, enable/disable and delete virtual hosts from the admin interface.
Automatic TLS certificates	Issue and renew Let's Encrypt certificates over ACME for each virtual host.
Certificate renewal scanner	A daily cron job renews certificates before they expire.
Nginx configuration	Per-host server blocks are generated automatically (HTTPS + HTTP→HTTPS redirect + uWSGI upstream).
Provisioning status	Each virtual host tracks a pending / ready / failed status, with retry on failure.
Domain linking	Associate mail domains with a virtual host directly from the domain forms.
Per-host theming	Override 5 colors and up to 3 logos (login, menu, creation form) per virtual host.

How it fits together

The plugin is made of two coupled pieces that are installed together:

• a Python package (modoboa_pro) registered as a Modoboa extension. It contributes the modoboa_pro.virtualhosts Django app — models, migrations, REST API, signal handlers and background jobs;
• a frontend remote (a Vue 3 application) that the Modoboa web interface loads at runtime to render the Virtual hosts admin page and the extra fields on the domain forms.

When you install the released package, both pieces ship inside it — you do not build the frontend yourself.

Provisioning lifecycle

Creating a virtual host kicks off a chain of background jobs:

bootstrap Nginx config  →  issue Let's Encrypt certificate
        →  generate final Nginx config  →  mark ready

While the chain runs, the virtual host is pending. When it finishes it becomes ready; if any step fails it becomes failed and the error is recorded so you can inspect it and retry. See Virtual hosts for details.

Next steps

• Requirements — what you need before installing.
• Installation — install the package into your instance.
• Configuration — enable Let's Encrypt and Nginx.