Modoboa — Modoboa 1.7.4 documentation

### Navigation

- index
- next |
- previous |
- Modoboa 1.7.4 documentation »
- Installation »

# Modoboa

This section describes the installation of the web interface (a Django project).

## Prepare the system

First of all, we recommand the following context:

- Use a dedicated system user
- Use a virtualenv 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 (Debian like system):

    > sudo apt-get install python-virtualenv python-pip
    > sudo useradd modoboa
    > sudo -i modoboa
    > virtualenv env
    (env)> source env/bin/activate
    (env)> pip install -U pip

Modoboa depends on external tools and some of them require compilation so you need a compiler and a few C libraries. Make sure to install the following system packages according to your distribution:

Debian/Ubuntu | CentOS
--- | ---
build-essential, python-dev, libxml2-dev, libxslt-dev, libjpeg-dev, librrd-dev, rrdtool, libffi-dev | gcc, gcc-c++, python-devel, libxml2-devel, libxslt-devel, libjpeg-turbo-devel, rrdtool-devel, rrdtool, libffi-devel

Then, install Modoboa:

    (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.

### PostgreSQL

Install the corresponding Python binding:

    (env)> pip install psycopg2

Then, create a user and a database:

    > sudo -i postgres
    >

### MySQL / MariaDB

Install the corresponding Python binding:

    (env)> pip install MySQL-Python

Then, create a user and a database:

    > mysqladmin -u root -p create modoboa

## Deploy an instance

`modoboa-admin.py`, a command line tool, lets you deploy a ready-to-use Modoboa site using only one instruction:

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

Note

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.

The list of available extensions can be found on the index page. Instructions to install them are available on each extensions page.

Note

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 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`.

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 commandline arguments.

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

    $ 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:

    #
    # Modoboa specific cron jobs
    #
    PYTHON=<PATH TO PYTHON BINARY>
    INSTANCE=<PATH TO MODOBOA INSTANCE>

    # Operations on mailboxes
    *       *       *       *       *       vmail   $PYTHON $INSTANCE/manage.py handle_mailbox_operations

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

    # Logs table cleanup
    0       0       *       *       *       root    $PYTHON $INSTANCE/manage.py cleanlogs

    # Logs parsing
    */5     *       *       *       *       root    $PYTHON $INSTANCE/manage.py logparser &> /dev/null

    # DNSBL checks
    */30    *       *       *       *       root    $PYTHON $INSTANCE/manage.py modo check_mx

    # Public API communication
    0       *       *       *       *       root    $PYTHON $INSTANCE/manage.py communicate_with_public_api

Now you can continue to the Web server section.

### Navigation

- index
- next |
- previous |
- Modoboa 1.7.4 documentation »
- Installation »