Background jobs

The plugin never performs slow or privileged work (ACME calls, filesystem writes, Nginx reloads) inside a web request. Everything is offloaded to RQ background jobs. This reference lists the jobs, the queues they run on, and the cron entry point — useful when operating the plugin or reading worker logs (everything logs to the modoboa.jobs logger).

Queues

Queue	Used for	Worker requirements
modoboa	Certificate issuance and renewal (ACME).	Outbound HTTPS to the ACME directory; write access to the ACME storage path.
privileged	Nginx config writes, enable/disable, deletion, reload.	Write access to the Nginx directories; able to run nginx -s reload.

Both workers must be running for provisioning to complete.

Provisioning jobs

These make up the provisioning chain that runs when a virtual host is created (or retried). The chain is strict — each job depends on the previous one succeeding, and a failure cancels the rest.

Job	Queue	Role
generate_bootstrap_nginx_config	privileged	Write the minimal HTTP-only config that serves the ACME challenge.
issue_letsencrypt_certificate	modoboa	Issue (or, with renewal=True, renew) the certificate.
generate_nginx_config	privileged	Write the final HTTPS config and reload Nginx.
mark_provisioning_ready	privileged	Terminal marker — flips the host to ready. Only runs if every upstream job succeeded.

A failure callback records the error and flips the host to failed; cancelled downstream jobs never run.

Lifecycle jobs

Enqueued in response to admin actions on existing virtual hosts:

Job	Queue	Trigger
apply_nginx_state	privileged	Enabling/disabling a host (toggles the site, reloads Nginx).
delete_nginx_config	privileged	Deleting a host (removes its config file, reloads Nginx).

Cron job

Job	Recommended schedule	Role
check_certificate_renewals	Daily, off-peak (17 3 * * *)	Scan enabled hosts and enqueue renewals for soon-to-expire certificates.

This is the only job you must schedule yourself. Register it in your instance's cron_config.py so the RQ scheduler runs it — see TLS certificates → Scheduling the job:

from modoboa_pro.virtualhosts import jobs as virtualhosts_jobs

register(
    virtualhosts_jobs.check_certificate_renewals,
    queue_name="modoboa",
    cron="17 3 * * *",
)

All other jobs are enqueued automatically by the plugin in response to virtual host creation, edits and admin actions — you do not schedule them.