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.
dovecot	Rights of the members of shared mailboxes (IMAP ACL).	doveadm (on the mail server), or the doveadm HTTP API. Also used by Modoboa itself.

Both the modoboa and privileged 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).

Shared mailbox jobs

Job	Queue	Trigger
apply_shared_mailbox_acls	dovecot	Creating a shared mailbox, adding, changing or removing a member. Gives every member its rights on every folder, and removes the rights of former members.
remove_shared_mailbox_acls	dovecot	A mailbox is no longer shared: its former members lose their access.

The status of the last run (pending, ready, failed) and its error are stored with the shared mailbox.

Cron jobs

Job	Recommended schedule	Role
check_certificate_renewals	Daily, off-peak (17 3 * * *)	Scan enabled hosts and enqueue renewals for soon-to-expire certificates.
reconcile_shared_mailboxes	Every 10 minutes (*/10 * * * *)	Apply the rights of the members again, to folders created on the server side since the last run (special folders, Sieve filters).

These are the only jobs you must schedule yourself. Register them in your instance's cron_config.py so the RQ scheduler runs them — see TLS certificates → Scheduling the job:

from modoboa_pro.sharedmailboxes import jobs as sharedmailboxes_jobs
from modoboa_pro.virtualhosts import jobs as virtualhosts_jobs

register(
    virtualhosts_jobs.check_certificate_renewals,
    queue_name="modoboa",
    cron="17 3 * * *",
)
register(
    sharedmailboxes_jobs.reconcile_shared_mailboxes,
    queue_name="modoboa",
    cron="*/10 * * * *",
)

All other jobs are enqueued automatically by the plugin in response to virtual host and shared mailbox changes — you do not schedule them.