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.

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

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 runs:

nginx -s reload

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.

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 nginx -s reload.	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.