Installation

This guide installs modoboa-pro into an existing Modoboa instance. All commands assume you have shell access to the server and can activate the Python virtual environment Modoboa runs in.

INFO

Throughout this page, <modoboa_instance> is the directory that contains your instance's manage.py and settings module (often /srv/modoboa/instance), and <venv> is the Python virtual environment Modoboa runs in.

1. Install the package

Install the package into the same virtual environment as Modoboa so it lands on the same PYTHONPATH:

$ <venv>/bin/pip install modoboa-pro

This pulls in the acme, josepy and cryptography dependencies described in Requirements.

TIP

If you install from a private index, pass --index-url / --extra-index-url as usual. The package ships the prebuilt frontend assets, so you do not need Node.js or a frontend build step on the server.

2. Register the apps

Open your instance's settings module (<modoboa_instance>/settings.py) and add the two plugin apps to the MODOBOA_APPS tuple, after the core entries:

MODOBOA_APPS = (
    "modoboa",
    "modoboa.core",
    "modoboa.lib",
    "modoboa.admin",
    # ... your other Modoboa apps ...

    # Modoboa Pro
    "modoboa_pro",            
    "modoboa_pro.virtualhosts",  
)

modoboa_pro registers the extension with Modoboa's extension pool (so the Virtual hosts menu entry and the frontend remote appear), while modoboa_pro.virtualhosts provides the Django app — models, migrations, REST API, signal handlers and background jobs.

3. Accept virtual host hostnames

Each virtual host introduces a new public hostname. Django rejects requests whose Host header is not in ALLOWED_HOSTS, so the plugin provides a dynamic ALLOWED_HOSTS that automatically includes every virtual host's name.

In the same settings.py, replace your static ALLOWED_HOSTS with:

from modoboa_pro.virtualhosts.allowed_hosts import VirtualHostAllowedHosts

ALLOWED_HOSTS = VirtualHostAllowedHosts(extra=["localhost", "mail.example.com"])

Pass any hostnames that are not virtual hosts (your primary hostname, localhost, monitoring probes…) via extra. Virtual host names are added automatically and the lookup is cached (and refreshed when virtual hosts change), so this stays cheap on every request.

WARNING

If you keep a plain ALLOWED_HOSTS = [...] list, requests to newly created virtual hosts will be rejected with a 400 Bad Request until you add each hostname by hand. Using VirtualHostAllowedHosts avoids that.

4. Apply database migrations

The plugin ships its own migrations for the VirtualHost model. Apply them:

$ cd <modoboa_instance>
$ <venv>/bin/python manage.py migrate virtualhosts

5. Collect static assets

The plugin ships the built frontend (the federation remote that the Modoboa web interface loads at runtime) as static files. Collect them so your web server can serve remoteEntry.js:

$ <venv>/bin/python manage.py collectstatic --noinput

6. Restart services

Restart the Modoboa web process and the RQ workers so the new code, settings and parameters are loaded:

$ systemctl restart modoboa          # web / uwsgi
$ systemctl restart modoboa-rq       # background workers

TIP

Service names depend on how your instance was deployed (systemd units, supervisor programs, Docker services…). Restart whatever runs the Modoboa web process and the RQ workers for both the modoboa and privileged queues.

7. Verify

Log in to the Modoboa web interface as a super administrator. You should see a new Virtual hosts entry in the admin navigation (globe icon). Opening it shows the (initially empty) virtual host list.

If the menu entry is missing:

• confirm both apps are in MODOBOA_APPS and the web process was restarted;
• confirm collectstatic ran and your web server serves the plugin's static files (the browser console will show a failed request for remoteEntry.js otherwise);
• confirm you are logged in as a SuperAdmin — the menu entry and the Virtual hosts route are restricted to that role.

Next step

The plugin is installed but the certificate and Nginx features are disabled by default. Continue with Configuration to enable them.