diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst
index d232a629a..90ba53228 100644
--- a/doc/manual_installation/modoboa.rst
+++ b/doc/manual_installation/modoboa.rst
@@ -10,53 +10,60 @@ This section describes the installation of the web interface (a
Prepare the system
------------------
-First of all, we recommand the following context:
+First of all, we recommend the following context:
-* Use a dedicated system user
-* Use a `virtualenv `_ to
- install the application because it will isolate it (and its
+* A dedicated system user
+* A `virtual environment
+ `_
+ 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):
+The following example illustrates how to realize this on Debian-based
+distributions using `virtualenv `_:
-.. sourcecode:: bash
+.. code-block:: console
- > sudo apt-get install python-virtualenv python-pip
- > sudo useradd modoboa
- > sudo -i -u modoboa
- > virtualenv env
- > source env/bin/activate
- (env)> pip install -U pip
+ # apt-get install virtualenv python3-pip
+ # useradd modoboa # create a dedicated user
+ # su -l modoboa # log in as the newly created user
+ $ virtualenv --python python3 ./env # create the virtual environment
+ $ source ./env/bin/activate # activate the virtual environment
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 |
-+==============================+
-|build-essential python-dev |
-|libxml2-dev libxslt-dev |
-|libjpeg-dev librrd-dev |
-|rrdtool libffi-dev libssl-dev |
-| |
-+------------------------------+
++-------------------------------+
+| Debian / Ubuntu |
++===============================+
+| build-essential python3-dev |
+| libxml2-dev libxslt-dev |
+| libjpeg-dev librrd-dev |
+| rrdtool libffi-dev libssl-dev |
++-------------------------------+
-+------------------------------+
-|CentOS |
-+==============================+
-|gcc gcc-c++ python-devel |
-|libxml2-devel libxslt-devel |
-|libjpeg-turbo-devel |
-|rrdtool-devel rrdtool |
-|libffi-devel |
-+------------------------------+
++-----------------------------+
+| CentOS |
++=============================+
+| gcc gcc-c++ python3-devel |
+| libxml2-devel libxslt-devel |
+| libjpeg-turbo-devel |
+| rrdtool-devel rrdtool |
+| libffi-devel |
++-----------------------------+
-Then, install Modoboa:
+.. note::
-.. sourcecode:: bash
+ Alternatively, you could rely on your distribution packages for the Modoboa
+ dependencies which require compilation - e.g. ``psycopg2`` - if the version
+ is compatible. In this case, you have to create your virtual environment
+ with the ``--system-site-packages`` option.
- (env)> pip install modoboa
+Then, install Modoboa by running:
+
+.. code-block:: console
+
+ (env)$ pip install modoboa
.. _database:
@@ -76,51 +83,73 @@ Thanks to Django, Modoboa is compatible with the following databases:
* SQLite
Since the last one does not require particular actions, only the first
-two ones are described.
+two ones are described. You should also read the notes for those database
+backends on the `official Django documentation
+`_.
PostgreSQL
**********
Install the corresponding Python binding:
-.. sourcecode:: bash
+.. code-block:: console
- (env)> pip install psycopg2
+ (env)$ pip install psycopg2
-Then, create a user and a database:
+.. note::
-.. sourcecode:: bash
+ Alternatively, you can install the ``python3-psycopg2`` package instead on
+ Debian-based distributions if your virtual environment was created with
+ ``--system-site-packages`` option.
- > sudo -i -u postgres
- >
+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:
+
+.. code-block:: console
+
+ # sudo -l -u postgres createuser --no-createdb modoboa
+ # sudo -l -u postgres createdb --owner=modoboa modoboa
MySQL / MariaDB
***************
Install the corresponding Python binding:
-.. sourcecode:: bash
+.. code-block:: console
- (env)> pip install mysqlclient
+ (env)$ pip install mysqlclient
+
+.. note::
+
+ Alternatively, you can install the ``python3-mysqldb`` package instead on
+ Debian-based distributions if your virtual environment was created with
+ ``--system-site-packages`` option.
.. note::
MariaDB 10.2 (and newer) require mysqlclient 1.3.11 (or newer).
-Then, create a user and a database:
+Then, create a user and a database. For example, to create the ``modoboa``
+database owned by a ``modoboa`` user, run the following SQL commands:
-.. sourcecode:: bash
+.. code-block:: mysql
- > mysqladmin -u root -p create modoboa
+ CREATE DATABASE modoboa;
+ CREATE USER 'modoboa'@'localhost' IDENTIFIED BY 'my-strong-password-here';
+ GRANT ALL PRIVILEGES ON modoboa.* TO 'modoboa'@'localhost';
Deploy an instance
------------------
-``modoboa-admin.py``, a command line tool, lets you deploy a
-*ready-to-use* Modoboa site using only one instruction::
+``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:
- (env)> modoboa-admin.py deploy instance --collectstatic \
- --domain --dburl default:database-url
+.. code-block:: console
+
+ (env)$ modoboa-admin.py deploy instance --collectstatic \
+ --domain --dburl default:
.. note::
@@ -160,12 +189,14 @@ 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.
+credentials as command line arguments.
You can consult the complete option list by running the following
-command::
+command:
- $ modoboa-admin.py help deploy
+.. code-block:: console
+
+ (env)$ modoboa-admin.py help deploy
Cron jobs
---------
@@ -174,35 +205,30 @@ A few recurring jobs must be configured to make Modoboa works as
expected.
Create a new file, for example :file:`/etc/cron.d/modoboa` and put the
-following content inside::
+following content inside:
- #
- # Modoboa specific cron jobs
- #
- PYTHON=
- INSTANCE=
+.. sourcecode:: bash
- # Operations on mailboxes
- * * * * * vmail $PYTHON $INSTANCE/manage.py handle_mailbox_operations
+ #
+ # Modoboa specific cron jobs
+ #
+ PYTHON=
+ INSTANCE=
- # Sessions table cleanup
- 0 0 * * * root $PYTHON $INSTANCE/manage.py clearsessions
+ # Operations on mailboxes
+ * * * * * vmail $PYTHON $INSTANCE/manage.py handle_mailbox_operations
- # Logs table cleanup
- 0 0 * * * root $PYTHON $INSTANCE/manage.py cleanlogs
+ # Generate DKIM keys (they will belong to the user running this job)
+ * * * * * root umask 077 && $PYTHON $INSTANCE/manage.py modo manage_dkim_keys
- # Logs parsing
- */5 * * * * root $PYTHON $INSTANCE/manage.py logparser &> /dev/null
- 0 * * * * root $PYTHON $INSTANCE/manage.py update_statistics
-
- # DNSBL checks
- */30 * * * * root $PYTHON $INSTANCE/manage.py modo check_mx
-
- # Public API communication
- 0 * * * * root $PYTHON $INSTANCE/manage.py communicate_with_public_api
-
- # Generate DKIM keys (they will belong to the user running this job)
- * * * * * root umask 077 && $PYTHON $INSTANCE/manage.py modo manage_dkim_keys
+ # Sessions table cleanup
+ 0 0 * * * modoboa $PYTHON $INSTANCE/manage.py clearsessions
+ # Logs table cleanup
+ 0 0 * * * modoboa $PYTHON $INSTANCE/manage.py cleanlogs
+ # DNSBL checks
+ */30 * * * * modoboa $PYTHON $INSTANCE/manage.py modo check_mx
+ # Public API communication
+ 0 * * * * modoboa $PYTHON $INSTANCE/manage.py communicate_with_public_api
.. _policy_daemon: