modoboa/doc-ng/installation/modoboa.md

---
title: manual step to install core component on modoboa
description: This guide describe how to install core on the modoboa platform
head:
  - - meta
    - name: 'keywords'
      content: 'modoboa, installation, core, mysql, postgresql, cron'
---

# Modoboa

This section describes the installation of the web interface (a [Django](https://www.djangoproject.com/) project).

This proposed configuration is the one you can find with `modoboa-installer`.

For up to date configuration, [take a look here](https://github.com/modoboa/modoboa-installer/tree/master/modoboa_installer/scripts/files/modoboa/)

## Prepare the system

First of all, we recommend the following context:

* A dedicated system user
* A [virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments)
  to install the application because it will isolate it (and its dependencies) from the rest of your system

The following example illustrates how to realize this on Debian-based distributions using [virtualenv](https://virtualenv.pypa.io/en/stable/):

``` shell
$ sudo apt-get install virtualenv python3-pip
$ sudo useradd modoboa  # create a dedicated user
$ sudo -u modoboa -i bash    # log in as the newly created user
$ virtualenv --python python3 ./env  # create the virtual environment
$ source ./env/bin/activate          # activate the virtual environment
```

::: warning
Modoboa depends on external tools and some of them require compilation
so you need a compiler and a few C libraries.
:::

::: tip INFORMATION
Make sure to install the following system packages according to your distribution:

* Debian / Ubuntu
  * build-essential
  * python3-dev
  * libxml2-dev
  * libxslt-dev
  * libjpeg-dev
  * librrd-dev
  * rrdtool
  * libffi-dev
  * libssl-dev pkg-config
  * libcairo2-dev

* CentOS / Redhat
  * gcc
  * gcc-c++
  * python3-devel
  * libxml2-devel
  * libxslt-devel
  * libjpeg-turbo-devel
  * rrdtool-devel rrdtool
  * libffi-devel
:::

::: info

Alternatively, you could rely on your distribution packages for the
Modoboa dependencies which require compilation
* e.g. `rrdtool` - if the version is compatible.
  In this case, you have to create your virtual environment
  with the `--system-site-packages` option, and the required
  system packages will be:

  * python3-wheel
  * python3-rrdtool
  * rrdtool
:::

Then, install Modoboa by running:

``` console
(env)$ pip install modoboa
```

## Database

::: warning
This documentation does not cover the installation of a database server
but only the setup of a functional database that Modoboa will use.
:::

Thanks to Django, Modoboa is compatible with the following databases:

- PostgreSQL
- MySQL / MariaDB
- SQLite

Since the last one does not require particular actions, only the first
two ones are described.

You should also read the notes for those database backends on the
[official Django documentation](https://docs.djangoproject.com/en/stable/ref/databases/).

### PostgreSQL

Install the corresponding Python binding:

``` shell
(env)$ pip install psycopg[binary]>=3.1
```

::: info
Ubuntu and Debian repositories contain python-psycopgX package but
starting modoboa 2.2.0 minimum version required is 3.1 and it has not
yet it these distro yet Prior modoboa version can run with `python3-psycopg2`.
:::

Then, create a user and a database.

For example, to create the `modoboa` database owned by a `modoboa` user,
run the following commands on your PostgreSQL server as `root` or admin user:

``` bash
$ sudo -l -u postgres createuser --no-createdb modoboa
$ sudo -l -u postgres createdb --owner=modoboa modoboa
```

### MySQL / MariaDB

Install the corresponding Python binding:

``` console
(env)$ pip install mysqlclient
```

::: tip
Alternatively, you can install the `python3-mysqldb` package instead on
Debian-based distributions if your virtual environment was created with
`--system-site-packages` option.
:::

:::: info NOTE
MariaDB 10.2 (and newer) require mysqlclient 1.3.11 (or newer).
::::

Then, create a user and a database. For example, to create the `modoboa`
database owned by a `modoboa` user, run the following SQL commands:

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

## Deploy an instance {#deployment}

`modoboa-admin.py` is a command line tool that lets you deploy a
*ready-to-use* Modoboa site. To create a new instance into `./instance`,
you just have to run the following command:

``` shell
(env)$ modoboa-admin.py deploy instance --collectstatic \
         --domain <hostname of your server> --dburl default:<database url>
```

::: info

You can install additional extensions during the deploy process. To do
so, use the `--extensions` option which accepts a list of names as
argument (`--extensions ext1 ext2 ...`). If you want to install all
extensions, just use the `all` keyword like this `--extensions all`.

If you choose to install extensions one at a time, you will have to add
their names in settings.py to `MODOBOA_APPS`. Also ensure that you have
the line `from modoboa_amavis.settings import *` at the end of this file
and possibly perform more steps. Check the documentation/readme of each
extensions for specific Instructions.

The list of available extensions can be found on the `index
page <../index>`{.interpreted-text role="doc"}. Instructions to install
them are available on each extensions page.
:::

::: tip TIPS

You can specify more than one database connection using the `--dburl`
option. Multiple connections are differentiated by a prefix.

The primary connection must use the `default:` prefix (as shown in the
example above). For the [amavis](http://modoboa-amavis.readthedocs.org)
extension, use the `amavis:` prefix. For example:
`--dburl default:<database url> amavis:<database url>`.

A database url should meet the following syntax
`<mysql|postgres>://[user:pass@][host:port]/dbname` **OR**
`sqlite:////full/path/to/your/database/file.sqlite`.

Fox example, if you were using postgres, you could setup your command
like this:
`modoboa-admin.py deploy instance_name --collectstatic --domain example.com --dburl default:postgres://user:pass@[localhost]/modoboa`
:::

The command will ask you a few questions, answer them and you\'re done.

If you need a **silent installation** (e.g. if you\'re using Salt-Stack,
Ansible or whatever), it's possible to supply the database credentials
as command line arguments.

You can consult the complete option list by running the following command:

``` shell
(env)$ modoboa-admin.py help deploy
```

## Cron jobs

A few recurring jobs must be configured to make Modoboa works as expected.

Create a new file, for example `/etc/cron.d/modoboa` and put the following content inside:

``` shell
#
# Modoboa specific cron jobs
#
PYTHON=<path to Python binary inside the virtual environment>
INSTANCE=<path to Modoboa instance>

# Sessions table cleanup
0     0  *  *  *  root  $PYTHON $INSTANCE/manage.py clearsessions
```

::: tip TIPS

**🥵 potential high load configuration**
Please note that above crontab might not be ideal on high load systems.
If you receive a fairly high amount of emails per day, you may want to
run modoboas logparser tasks *once per night*.

This has the down side that the statistic graph and message log within
the UI are updated once per day only.
:::

## Policy daemon {#policy_daemon}

Modoboa comes with a built-in
[Policy Daemon for Postfix](http://www.postfix.org/SMTPD_POLICY_README.html).
Current features are:

* Define daily sending limits for domains and/or accounts

A [redis server](https://redis.io/) is required to run this new daemon.

You can launch it manually using the following command:

``` shell
(env) $ python manage.py policy_daemon
```

But we recommend an automatic start using `systemd` or `supervisor`.

Here is a configuration example for `supervisor`:

``` ini
[program:policyd]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py policy_daemon
directory=<modoboa user home dir>
redirect_stderr=true
user=modoboa
numprocs=1
```

It will listen by default on `127.0.0.1` and port `9999`.

The policy daemon won't do anything unless you tell
`postfix <policyd_config>` to use it.

## RQ daemon

Modoboa uses [RQ](https://python-rq.org) as a job handler for async task.

A [redis server](https://redis.io/) is required to run this new daemon.

A worker needs to be launched in the venv.

You can launch it manually using the following command:

``` shell
(env)> rq worker modoboa dkim dovecot
```

But we recommend an automatic start using `systemd` or `supervisor`.

You'll find configuration examples for `supervisor` in next sections.

## Cron scheduler
``` ini
[program:rq-scheduler]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py rqcron <path to Modoboa instance>/instance/cron_config.py
directory=<modoboa user home dir>
user=<modoboa user>
redirect_stderr=true
numprocs=1
stopsignal=TERM
```

## Privileged worker
``` ini
[program:modoboa-privileged-worker]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py rqworker privileged
directory=<modoboa user home dir>
user=root
redirect_stderr=true
numprocs=1
stopsignal=TERM
```

## General worker
``` ini
[program:modoboa-base-worker]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py rqworker modoboa
directory=<modoboa user home dir>
user=<modoboa user>
redirect_stderr=true
numprocs=1
stopsignal=TERM
```

## DKIM worker
``` ini
[program:modoboa-dkim-worker]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py rqworker dkim
directory=<modoboa user home dir>
user=<opendkim user>
redirect_stderr=true
numprocs=1
stopsignal=TERM
```

## Dovecot worker
``` ini
[program:modoboa-dovecot-worker]
autostart=true
autorestart=true
command=<path to Python binary inside the virtual environment> <path to Modoboa instance>/manage.py rqworker dovecot
directory=<modoboa user home dir>
user=vmail
redirect_stderr=true
numprocs=1
stopsignal=TERM
```

Now you can continue to the [webserver](webserver) section.