Configuration

All plugin settings live in the Modoboa web interface under Modoboa → Parameters → Virtual hosts (visible to super administrators). They are stored in Modoboa's parameter table — there is nothing to edit in settings.py for the options below, except the two Django-level settings described at the end.

The parameters are split into two groups: ACME / Let's Encrypt and Nginx. Both features are disabled by default; the related fields only appear once you enable the corresponding toggle.

ACME / Let's Encrypt

Controls automatic TLS certificate issuance and renewal for virtual hosts.

Setting	Description	Default
Enable Let's Encrypt	Automatically generate Let's Encrypt certificates for virtual hosts.	false
ACME account storage path	Directory where the ACME account key, registration and issued certificates are stored. Must be writable by the worker that runs certificate jobs.	/var/lib/modoboa/acme
Account email	Email address used when registering the ACME account with the certificate authority (used for expiry notices).	—
Renewal threshold (days)	Renew certificates whose remaining validity falls below this many days. Accepts 1–89.	30

TIP

Let's Encrypt advises a renewal threshold of 30 days: it leaves enough slack to retry issuance several times before the certificate actually expires.

When Enable Let's Encrypt is on, creating a virtual host triggers an ACME HTTP-01 challenge, so each hostname must resolve in public DNS and be reachable on port 80 from the internet. See TLS certificates for the full flow and the renewal cron job.

Nginx

Controls automatic generation of per-virtual-host Nginx server blocks.

Setting	Description	Default
Generate Nginx configuration	Automatically generate an Nginx server configuration when a new virtual host is created.	false
Configuration directory	Directory where per-virtual-host configuration files are written (e.g. /etc/nginx/sites-available on Debian/Ubuntu).	/etc/nginx/sites-available
Enabled sites directory	Optional. When set, a symlink to each configuration file is created here (e.g. /etc/nginx/sites-enabled). Leave empty when the configuration directory is loaded directly by Nginx.	/etc/nginx/sites-enabled
uWSGI socket path	Path to the uWSGI socket exposing the Modoboa application — the upstream the generated config proxies to.	/run/uwsgi/app/modoboa/socket
Modoboa instance path	Filesystem path to the Modoboa instance, used to locate static and frontend assets referenced by the generated config.	/srv/modoboa/instance

WARNING

The worker that runs Nginx jobs (the privileged queue) must have write access to the configuration and enabled-sites directories. The plugin writes the files and manages the symlinks, but it does not reload Nginx for you — see Nginx integration for how to wire up a reload.

Django-level settings

Two settings are read from your instance's settings.py (not from the parameters panel) and control how the ACME client talks to the certificate authority:

# User-Agent header sent with ACME API requests.
ACME_USER_AGENT = "modoboa-pro"

# ACME directory URL of the certificate authority.
# Production Let's Encrypt:
ACME_DIRECTORY_URL = "https://acme-v02.api.letsencrypt.org/directory"
# Staging (use while testing — issues untrusted certs, far higher rate limits):
# ACME_DIRECTORY_URL = "https://acme-staging-v02.api.letsencrypt.org/directory"

TIP

Point ACME_DIRECTORY_URL at the staging environment while you validate your setup. Staging has much higher rate limits, so you can create and destroy test virtual hosts freely; the certificates it issues are not trusted by browsers, which is expected. Switch to production once issuance succeeds end-to-end.

Recommended order

1. Set ACME_DIRECTORY_URL (staging first) in settings.py and restart.
2. Enable Nginx configuration and fill in the paths for your distribution.
3. Enable Let's Encrypt, set the account email and storage path.
4. Schedule the renewal cron job.
5. Create a test virtual host (see Virtual hosts).

Next step

You are ready to create and manage virtual hosts.