From ArchWiki

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: Too many changes needed to list them all. (Discuss in Talk:Modoboa)

Modoboa is a mail hosting and management platform including a modern and simplified Web User Interface designed to work with Postfix and Dovecot.

For context, please see List of applications/Internet#Mail servers

When setting up this program is seems like the aur repo is a basic way to install the dependencies but lacks a lot of the system setup that you currently have to do manually. Here is a few details on how to setup modoboa as a system service.

Note: There are a few issues right now when installing Modoboa so this wiki article is currently unfinished and needs revision.


Tip: As of writing this article, the aur repo is out of date as of python3.12. There is a user maintained repo to install modoboaAUR which installs the python module installed into /usr/lib/python3.12/site-packages/modoboa or whichever python version you are currently running. But it is missing a number of packages including python-django-rqAUR python-magic python-tldextract python-reportlab python-aiosmtplibAUR and a version conflict with python-lxml. Until those are fixed please use the python installation through pip

To install modoboa through pip please create a python-virtualenv. You can also make a modoboa user if you want to encapsulate the program.

Find a place to put modoboa then run:

mkdir modoboa
cd /modoboa
virtualenv env
. env/bin/

Then once you are in the virtual environment install modoboa:

pip install modoboa

If you feel inclined you can read the documentation. Additionally here is a link to the github for reference: Modoboa-Github.

Once installing modoboaAUR you will have access to two command line utilities:

  • modoboa-cli


Modoboa requires a database instance; because it uses Django is easily supports:

Please follow the installation process for whichever database you want to use and set it up before continuing.

Using PostgreSQL

If you use PostgreSQL you must install the python dependency [1]

pip install psycopg[binary]>=3.1

Then create a user and datbase for modoboa to use:

sudo -l -u postgres createuser --no-createdb modoboa
sudo -l -u postgres createdb --owner=modoboa modoboa

Using MySQL or MariaDB

For MySQL or MariaDB you must install the python dependency [2]

pip install mysqlclient

Once installed create an associated user:

CREATE USER 'modoboa'@'localhost' IDENTIFIED  BY 'my-strong-password-here';
GRANT ALL PRIVILEGES ON modoboa.* TO 'modoboa'@'localhost';

Using SQLite

No required dependencies besides installing SQLite.

Making a Modoboa Instance

To start with Modoboa, until the aur repo is fixed follow the instructions above on installing a virtual environment and pip install modoboa. Then you can proceed to creating the Django project.

Building your Instance

Now deploy your modoboa. Once you have everything installed you can create an instance of the Django web-server using the command deploy instance .... This will create a Django project in the directory ./instance in your working directory.

By default without introducing any database arguments Modoboa, it will prompt you for which database you want to use through an interactive console. If you use the SQLite method it will create a database in your working directory under the name ./instance. deploy instance --collectstatic --domain <hostname of your server>

The interactive prompt will ask you which database you want and to start you can just use sqlite3 while you are setting up your system:

Configuring database connection: default
Database type (mysql, postgres or sqlite3): sqlite3

Specifying a Sqlite Location

Alternatively, you can specify the location of your SQLite database. deploy instance --collectstatic --domain <hostname of your server> --dburl default:sqlite:////full/path/to/your/database/file.sqlite

Other Databases

If you are going to use an alternative database use this syntax <mysql|postgres>://[user:pass@][host:port]/dbname for the connection string. Here is a filled out example, deploy instance_name --collectstatic --domain --dburl default:postgres://user:pass@[localhost]/modoboa

For more information on running the different databases see help deploy

Or read the documentation

Running the Django Instance

Before you can run modoboa you need to setup your webserver because it is dependent on your domain.

Once you have used to create a instance directory, you can cd into the directory and there will be a file which would be familiar to anyone who uses Django.

To view the various services in the django project you can run in the instance directory:


Setting up Nginx

In this example we will use Gunicorn to run a unix socket for the modoboa webserver. While in the virtual environment for modoboa, please install gunicorn to host the webserver. You can also use uwsgi.

pip install gunicorn

Then we can setup a Nginx config accordingly. Make your configuration file however you do it. I have a /etc/nginx/available directory that I place config files then system link them to /etc/nginx/enables which is included in the /etc/nginx/nginx.conf.

I placed the the following in /etc/nginx/available/modoboa.conf

upstream modoboa {
     server      unix:/var/run/gunicorn/modoboa.sock fail_timeout=0;


server {
     root <modoboa_instance_path>;

     access_log  /var/log/nginx/modoboa.access.log;
     error_log /var/log/nginx/modoboa.error.log;

     location /sitestatic/ {
             autoindex on;

     location /media/ {
             autoindex on;

     location / {
             proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
             proxy_set_header Host $http_host;
             proxy_redirect off;
             proxy_set_header X-Forwarded-Protocol ssl;
             proxy_pass http://modoboa;

Now for ssl you need to install certbot and the nginx plugin certbot-nginx. Then run

sudo certbot --nginx run

To enable tls.