Nginx integration

When Generate Nginx configuration is enabled (see Configuration), the plugin writes a dedicated Nginx server block for each virtual host and keeps it in sync with the host's lifecycle. This page explains what gets written, where, and what you must provide on the system side.

What the plugin generates

Each virtual host goes through two configuration writes during provisioning:

1. Bootstrap config — a minimal HTTP-only server block whose only job is to serve the ACME HTTP-01 challenge from the webroot, so the certificate can be issued.
2. Final config — once the certificate exists, an HTTPS server block that:
   • terminates TLS using the host's fullchain.pem / privkey.pem;
   • redirects HTTP → HTTPS;
   • proxies application traffic to Modoboa over the configured uWSGI socket;
   • serves static and frontend assets from the Modoboa instance path;
   • routes the mail-client autoconfiguration endpoints to Modoboa (see below).

Configuration files are named <hostname>.conf and written to the Configuration directory parameter (default /etc/nginx/sites-available).

Mail-client autoconfiguration

Modoboa serves the mail-client discovery endpoints at its root, and the final config routes them to the application:

• Thunderbird — /.well-known/autoconfig/mail/config-v1.1.xml (rewritten onto Modoboa's /mail/config-v1.1.xml) and /mail/config-v1.1.xml;
• Outlook — /autodiscover/autodiscover.xml;
• Apple — /mobileconfig.

This works on the virtual host's own hostname and certificate, so no extra DNS record or certificate is required for the common case.

The Autoconfig/autodiscover subdomains parameter (off by default) additionally puts autoconfig.<domain> and autodiscover.<domain> into the config's server_name (bootstrap and final blocks) — for clients that probe those dedicated subdomains. <domain> is each mail domain served by the virtual host rather than its own hostname (a client looking up user@example.com probes autoconfig.example.com), falling back to the domain of the hostname while no domain is attached. Those names are also added as certificate SANs, so turning this on has DNS and certificate prerequisites: see Configuration → Mail-client autoconfiguration. The per-host access_log / error_log stay named after the primary hostname regardless.

Enabled vs. available

How a host's config becomes active depends on the Enabled sites directory parameter:

• Set (e.g. /etc/nginx/sites-enabled, the Debian/Ubuntu layout): the plugin creates a symlink from this directory to the .conf file in the configuration directory. Enabling/disabling a virtual host adds or removes that symlink.
• Empty: no symlinks are managed — the plugin assumes your Nginx loads the configuration directory directly (e.g. include /etc/nginx/sites-available/*.conf;).

Deleting a virtual host removes its .conf file (and symlink, if any).

Reloading Nginx

After writing, enabling, disabling or deleting a configuration, the plugin reloads Nginx. How it does so is controlled by the Reload method parameter:

Method	Command	When to pick it
Automatic (default)	systemctl reload nginx, falling back to nginx -s reload	The host is unknown or standard — detection uses /run/systemd/system, so a systemd machine gets systemctl and a container gets the signal.
Signal (nginx -s reload)	nginx -s reload	Nginx isn't managed by systemd (container, supervisor, custom init), or the worker may signal the master process directly.
systemctl reload nginx	systemctl reload nginx	A systemd host where the worker can't touch the pid file but has a sudo rule (or runs as root). Never falls back to the signal — the choice is honoured as-is.

In Automatic mode the fallback only triggers when the systemctl call actually fails, so a working systemd host never runs the signal.

Reload failures are logged and swallowed (to the modoboa.jobs logger) so a single bad reload doesn't wedge the background worker — but it does mean a failed reload won't show up as a failed provisioning. Watch the logs if a change doesn't take effect; the log line names the command that failed and its stderr.

System prerequisites

For the generated configuration to work, you must provide the following on the host:

Requirement	Why
Nginx installed and loading the configuration directory.	The plugin only writes files; it doesn't install or configure Nginx's top-level setup.
The privileged RQ worker can write the config & enabled-sites directories.	All Nginx jobs run on that queue and write directly to disk.
The worker can run the reload command (systemctl reload nginx or nginx -s reload, per the Reload method parameter).	That's how changes are applied. Typically the worker runs as root or via an appropriately scoped sudo rule.
Correct uWSGI socket path and instance path parameters.	The generated proxy/uwsgi_pass and asset roots point at these.

WARNING

The privileged queue exists precisely because these operations need elevated filesystem and reload permissions. Run that worker as a user that can write the Nginx directories and reload Nginx; the regular modoboa queue worker does not need those rights.

TIP

If you prefer not to let the worker reload Nginx directly, you can leave the reload to fail quietly and trigger reloads yourself (for example, an external systemctl reload nginx on a timer, or an inotify/path watch on the configuration directory). The generated files are valid Nginx configuration either way.

Doing it yourself instead

If you already manage Nginx with your own tooling (Ansible, a reverse proxy, a load balancer terminating TLS…), leave Generate Nginx configuration disabled. The plugin will then only manage virtual host records, domain links, theming and — if you keep it enabled — certificates, leaving the web server configuration entirely to you.