From 8c542dd405bf6d3df05e9ca5f41b1908d3155052 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 11 May 2020 12:49:41 +0200 Subject: [PATCH 1/5] Comment and improve highlight in 'Prepare the system' doc --- doc/manual_installation/modoboa.rst | 67 +++++++++++++++-------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst index 61d48fe02..a1281a722 100644 --- a/doc/manual_installation/modoboa.rst +++ b/doc/manual_installation/modoboa.rst @@ -10,53 +10,54 @@ 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: -.. sourcecode:: bash +Then, install Modoboa by running: - (env)> pip install modoboa +.. code-block:: console + + (env)$ pip install modoboa .. _database: From dd432e099b559202851ae426d167bd2e30ec5239 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 11 May 2020 12:52:12 +0200 Subject: [PATCH 2/5] Complete doc of database setup --- doc/manual_installation/modoboa.rst | 34 +++++++++++++++++++---------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst index a1281a722..163a236c0 100644 --- a/doc/manual_installation/modoboa.rst +++ b/doc/manual_installation/modoboa.rst @@ -77,42 +77,52 @@ 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: -.. sourcecode:: bash - > 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:: 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 ------------------ From 31c615e6844cc4741c4c118d049c05470114bf80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 11 May 2020 12:53:35 +0200 Subject: [PATCH 3/5] Add a note for --system-site-packages usage in install doc --- doc/manual_installation/modoboa.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst index 163a236c0..f9e5fe63a 100644 --- a/doc/manual_installation/modoboa.rst +++ b/doc/manual_installation/modoboa.rst @@ -52,6 +52,12 @@ following system packages according to your distribution: | libffi-devel | +-----------------------------+ +.. note:: + + 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. Then, install Modoboa by running: @@ -90,7 +96,11 @@ Install the corresponding Python binding: (env)$ pip install psycopg2 +.. note:: + Alternatively, you can install the ``python3-psycopg2`` package instead on + Debian-based distributions if your virtual environment was created with + ``--system-site-packages`` option. 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 @@ -110,6 +120,11 @@ Install the corresponding Python binding: (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:: From d9662e76ba8d9257cb1c2917b562f0b11608d46e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 11 May 2020 12:54:17 +0200 Subject: [PATCH 4/5] Fix and improve cron jobs in doc * Do not run commands as root when it is not needed * Remove commands which are part of modoboa-stats --- doc/manual_installation/modoboa.rst | 43 +++++++++++++---------------- 1 file changed, 19 insertions(+), 24 deletions(-) diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst index f9e5fe63a..40a3c1e40 100644 --- a/doc/manual_installation/modoboa.rst +++ b/doc/manual_installation/modoboa.rst @@ -200,35 +200,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 Now you can continue to the :ref:`webserver` section. From 1931c19eeba0e95f4b1058cf7adf473edde416f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 11 May 2020 14:37:39 +0200 Subject: [PATCH 5/5] Improve other commands' highlight in manual install doc --- doc/manual_installation/modoboa.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst index 40a3c1e40..042e693c7 100644 --- a/doc/manual_installation/modoboa.rst +++ b/doc/manual_installation/modoboa.rst @@ -142,11 +142,14 @@ database owned by a ``modoboa`` user, run the following SQL commands: 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:: @@ -186,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 ---------