From 3decd518adbe90a4e48e599fe9c9c2699ecf0407 Mon Sep 17 00:00:00 2001 From: Antoine Nguyen Date: Thu, 29 Sep 2016 21:29:19 +0200 Subject: [PATCH] Documentation refactor. wip --- doc/getting_started.rst | 203 -------------- doc/getting_started/upgrade.rst | 302 --------------------- doc/index.rst | 5 +- doc/installation.rst | 463 ++++++++++++++++++++++++++++++++ doc/upgrade.rst | 336 +++++++++++++++++++++++ 5 files changed, 801 insertions(+), 508 deletions(-) delete mode 100644 doc/getting_started.rst create mode 100644 doc/installation.rst create mode 100644 doc/upgrade.rst diff --git a/doc/getting_started.rst b/doc/getting_started.rst deleted file mode 100644 index 1c80da81c..000000000 --- a/doc/getting_started.rst +++ /dev/null @@ -1,203 +0,0 @@ -############### -Getting started -############### - -************ -Installation -************ - -Using the installer -=================== - -If you start from scratch and want to deploy a complete mail server, -you will love the `modoboa installer -`_! It is the easiest -and the quickest way to setup a fully functional server (modooba, -postfix, dovecot, amavis and more) on one machine. - -.. warning:: - - For now, only Debian and CentOS based Linux distributions are - supported. We do our best to improve compatibility but if you use - another Linux or a UNIX system, you will have to install Modoboa - :ref:`by_hand`. - -To use it, just run the following commands in your terminal:: - - $ git clone https://github.com/modoboa/modoboa-installer - $ cd modoboa-installer - $ sudo ./run.py - -Wait a few minutes and you're done \o/ - -.. _by_hand: - -By hand -======= - -In case you already have a running server (postfix, dovecot, etc.) or -you want to build a multi-machine architecture, you can install -Modoboa manually. - -Since Modoboa is a web application written in Python, the procedure -can be splitted in two parts: installing the application and -installing a web server. - -Modoboa -------- - -Prepare the system -~~~~~~~~~~~~~~~~~~ - -First of all, we recommand the following context: - -* using a dedicated system user -* using 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 - -FIXME: dépendances système pour compilation - -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 --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 :doc:`index - page <../index>`. 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: amavis:``. - - A database url should meet the following syntax - ``://[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. You can now go to the :ref:`first_use` section. - -In case 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 - - - -******* -Upgrade -******* - -.. warning:: - - The new version you are going to install may need to modify your - database. Before you start, make sure to backup everything! - -Most of the time, upgrading your installation to a newer Modoboa -version only requires a few actions. In any case, you will need to -apply the general procedure first and then check if the version you -are installing requires specific actions. - -.. note:: - - In case you use a dedicated user and/or a virtualenv, do not forget to - use them:: - - > sudo -i - > source /bin/activate - -The general procedure is as follows:: - - > pip install modoboa== - > cd - > python manage.py migrate - > python manage.py collectstatic - -Once done, check if the version you are installing requires -:ref:`specific_upgrade_instructions`. - -Finally, restart your web server. diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst index 9c41de0f0..60afc1ad9 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/getting_started/upgrade.rst @@ -42,308 +42,6 @@ version you're installing. To finish, restart the web server process according to the environment you did choose. See :ref:`webservers` for more details. - -.. _specific_upgrade_instructions: - -***************************** -Specific upgrade instructions -***************************** - -1.6.0 -===== - -An interesting feature brougth by this version is the capability to -make different checks about MX records. For example, Modoboa can -query main `DNSBL `_ providers -for every defined domain. With this, you will quickly now if one the -domains you manage is listed or not. To activate it, add the -following line to your crontab:: - - */30 * * * * /manage.py modo check_mx - -The communication with Modoboa public API has been reworked. Instead -of sending direct synchronous queries (for example to check new -versions), a cron job has been added. To activate it, add the -following line to your crontab:: - - 0 * * * * /manage.py communicate_with_public_api - -Please also note that public API now uses TLS so you must update your -configuration as follows:: - - MODOBOA_API_URL = 'https://api.modoboa.org/1/' - -1.5.0 -===== - -The API has been greatly improved and a documentation is now -available. To enable it, add ``'rest_framework_swagger'`` to the -``INSTALLED_APPS`` variable in :file:`settings.py` as follows:: - - INSTALLED_APPS = ( - 'django.contrib.auth', - 'django.contrib.contenttypes', - 'django.contrib.sessions', - 'django.contrib.messages', - 'django.contrib.sites', - 'django.contrib.staticfiles', - 'reversion', - 'rest_framework.authtoken', - 'rest_framework_swagger', - ) - -Then, add the following content into :file:`settings.py`, just after -the ``REST_FRAMEWORK`` variable:: - - SWAGGER_SETTINGS = { - "is_authenticated": False, - "api_version": "1.0", - "exclude_namespaces": [], - "info": { - "contact": "contact@modoboa.com", - "description": ("Modoboa API, requires a valid token."), - "title": "Modoboa API", - } - } - -You're done. The documentation is now available at the following address: - - http:///docs/api/ - -Finally, if you find a ``TEMPLATE_CONTEXT_PROCESSORS`` variable in -your :file:`settings.py` file, make sure it looks like this:: - - TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + [ - 'modoboa.core.context_processors.top_notifications', - ] - -1.4.0 -===== - -.. warning:: - - Please make sure to use Modoboa 1.3.5 with an up-to-date database - before an upgrade to 1.4.0. - -.. warning:: - - Do not follow the regular upgrade procedure for this version. - -Some extension have been moved back into the main repository. The main -reason for that is that using Modoboa without them doesn't make sense. - -First of all, you must rename the following applications listed inside -the ``MODOBOA_APPS`` variable: - -+--------------------------+--------------------+ -|Old name |New name | -+==========================+====================+ -|modoboa_admin |modoboa.admin | -+--------------------------+--------------------+ -|modoboa_admin_limits |modoboa.limits | -+--------------------------+--------------------+ -|modoboa_admin_relaydomains|modoboa.relaydomains| -+--------------------------+--------------------+ - -Then, apply the following steps: - -#. Uninstall old extensions:: - - $ pip uninstall modoboa-admin modoboa-admin-limits modoboa-admin-relaydomains - -#. Install all extension updates using pip (check the *Modoboa > Information* page) - -#. Manually migrate database:: - - $ cd - $ python manage.py migrate auth - $ python manage.py migrate admin 0001 --fake - $ python manage.py migrate admin - $ python manage.py migrate limits 0001 --fake - $ python manage.py migrate relaydomains 0001 --fake - $ python manage.py migrate - -#. Finally, update static files:: - - $ python manage.py collectstatic - -This version also introduces a REST API. To enable it: - -#. Add ``'rest_framework.authtoken'`` to the ``INSTALLED_APPS`` variable - -#. Add the following configuration inside ``settings.py``:: - - # Rest framework settings - - REST_FRAMEWORK = { - 'DEFAULT_AUTHENTICATION_CLASSES': ( - 'rest_framework.authentication.TokenAuthentication', - ), - 'DEFAULT_PERMISSION_CLASSES': ( - 'rest_framework.permissions.IsAuthenticated', - ) - } - -#. Run the following command:: - - $ python manage.py migrate - -1.3.5 -===== - -To enhance security, Modoboa now checks the `strength of user -passwords _`. - -To use this feature, add the following configuration into the ``settings.py`` file:: - - # django-passwords - - PASSWORD_MIN_LENGTH = 8 - - PASSWORD_COMPLEXITY = { - "UPPER": 1, - "LOWER": 1, - "DIGITS": 1 - } - - -1.3.2 -===== - -Modoboa now uses the *atomic requests* mode to preserve database -consistency (`reference -`_). - -To enable it, update the ``DATABASES`` variable in ``settings.py`` as -follows:: - - DATABASES = { - "default": { - # stuff before... - "ATOMIC_REQUESTS": True - }, - "amavis": { - # stuff before... - "ATOMIC_REQUESTS": True - } - } - -1.3.0 -===== - -This release does not bring awesome new features but it is a necessary -bridge to the future of Modoboa. All extensions now have their own git -repository and the deploy process has been updated to reflect this -change. - -Another important update is the use of Django 1.7. Besides its new -features, the migration system has been reworked and is now more -robust than before. - -Before we begin with the procedure, here is a table showing old -extension names and their new name: - -+----------------------------------------+--------------------------+--------------------------+ -|Old name |New package name |New module name | -+========================================+==========================+==========================+ -|modoboa.extensions.admin |modoboa-admin |modoboa_admin | -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.limits |modoboa-admin-limits |modoboa_admin_limits | -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.postfix_autoreply |modoboa-postfix-autoreply |modoboa_postfix_autoreply | -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.postfix_relay_domains|modoboa-admin-relaydomains|modoboa_admin_relaydomains| -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.radicale |modoboa-radicale |modoboa_radicale | -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.sievefilters |modoboa-sievefilters |modoboa_sievefilters | -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.stats |modoboa-stats |modoboa_stats | -+----------------------------------------+--------------------------+--------------------------+ -|modoboa.extensions.webmail |modoboa-webmail |modoboa_webmail | -+----------------------------------------+--------------------------+--------------------------+ - -Here are the required steps: - -#. Install the extensions using pip (look at the second column in the table above):: - - $ pip install - -#. Remove ``south`` from ``INSTALLED_APPS`` - -#. Rename old extension names inside ``MODOBOA_APPS`` (look at the third column in the table above) - -#. Remove ``modoboa.lib.middleware.ExtControlMiddleware`` from ``MIDDLEWARE_CLASSES`` - -#. Change ``DATABASE_ROUTERS`` to:: - - DATABASE_ROUTERS = ["modoboa_amavis.dbrouter.AmavisRouter"] - -#. Run the following commands:: - - $ cd - $ python manage.py migrate - -#. Reply ``yes`` to the question - -#. Run the following commands:: - - $ python manage.py load_initial_data - $ python manage.py collectstatic - -#. The cleanup job has been renamed in Django, so you have to modify your crontab entry:: - - - 0 0 * * * /manage.py cleanup - + 0 0 * * * /manage.py clearsessions - -1.2.0 -===== - -A new notification service let administrators know about new Modoboa -versions. To activate it, you need to update the -``TEMPLATE_CONTEXT_PROCESSORS`` variable like this:: - - from django.conf import global_settings - - TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + ( - 'modoboa.core.context_processors.top_notifications', - ) - -and to define the new ``MODOBOA_API_URL`` variable:: - - MODOBOA_API_URL = 'http://api.modoboa.org/1/' - -The location of external static files has changed. To use them, add a -new path to the ``STATICFILES_DIRS``:: - - # Additional locations of static files - STATICFILES_DIRS = ( - # Put strings here, like "/home/html/static" or "C:/www/django/static". - # Always use forward slashes, even on Windows. - # Don't forget to use absolute paths, not relative paths. - "/bower_components", - ) - -Run the following commands to define the hostname of your instance:: - - $ cd - $ python manage.py set_default_site - -If you plan to use the Radicale extension: - -#. Add ``'modoboa.extensions.radicale'`` to the ``MODOBOA_APPS`` variable - -#. Run the following commands:: - - $ cd - $ python manage.py syncdb - -.. warning:: - - You also have to note that the :file:`sitestatic` directory has moved from - ```` to ```` (it's probably - the parent directory). You have to adapt your web server configuration - to reflect this change. 1.1.7: manual learning for SpamAssassin ======================================= diff --git a/doc/index.rst b/doc/index.rst index 381770048..0de085cd4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,11 +13,10 @@ Getting started .. toctree:: :maxdepth: 2 - getting_started/install - getting_started/upgrade + installation + upgrade getting_started/configuration - ******* Plugins ******* diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 000000000..9aecdc052 --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,463 @@ +############ +Installation +############ + +Using the installer +=================== + +If you start from scratch and want to deploy a complete mail server, +you will love the `modoboa installer +`_! It is the easiest +and the quickest way to setup a fully functional server (modooba, +postfix, dovecot, amavis and more) on one machine. + +.. warning:: + + For now, only Debian and CentOS based Linux distributions are + supported. We do our best to improve compatibility but if you use + another Linux or a UNIX system, you will have to install Modoboa + :ref:`by_hand`. + +To use it, just run the following commands in your terminal: + +.. sourcecode:: bash + + > git clone https://github.com/modoboa/modoboa-installer + > cd modoboa-installer + > sudo ./run.py + +Wait a few minutes and you're done \o/ + +.. _by_hand: + +By hand +======= + +In case you already have a running server (postfix, dovecot, etc.) or +you want to build a multi-machine architecture, you can install +Modoboa manually. + +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): + +.. sourcecode:: bash + + > 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 + +FIXME: dépendances système pour compilation + +Then, install Modoboa: + +.. sourcecode:: bash + + (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: + +.. sourcecode:: bash + + (env)> pip install psycopg2 + +Then, create a user and a database: + +.. sourcecode:: bash + + > sudo -i postgres + > + +MySQL / MariaDB +*************** + +Install the corresponding Python binding: + +.. sourcecode:: bash + + (env)> pip install MySQL-Python + +Then, create a user and a database: + +.. sourcecode:: bash + + > 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 --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 :doc:`index + page <../index>`. 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: amavis:``. + + A database url should meet the following syntax + ``://[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. You can now go to the :ref:`first_use` section. + +In case 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 + +.. _webservers: + +Web server +---------- + +.. note:: + + The following instructions are meant to help you get your site up + and running quickly. However it is not possible for the people + contributing documentation to Modoboa to test every single + combination of web server, wsgi server, distribution, etc. So it is + possible that **your** installation of uwsgi or nginx or Apache or + what-have-you works differently. Keep this in mind. + +.. _apache2: + +Apache2 +******* + +First, make sure that ``mod_wsgi`` is installed on your server. + +Create a new virtualhost in your Apache configuration and put the +following content inside:: + + + ServerName + DocumentRoot + + Alias /media/ /media/ + /media> + Order deny,allow + Allow from all + + + Alias /sitestatic/ /sitestatic/ + /sitestatic> + Order deny,allow + Allow from all + + + WSGIScriptAlias / //wsgi.py + + + +This is just one possible configuration. + +To use mod_wsgi daemon mode, add the two following directives just +under ``WSGIScriptAlias``:: + + WSGIDaemonProcess example.com python-path=:/lib/python2.7/site-packages + WSGIProcessGroup example.com + +Replace values between ``<>`` with yours. If you don't use a +`virtualenv `_, just +remove the last part of the ``WSGIDaemonProcess`` directive. + +.. note:: + + You will certainly need more configuration in order to launch + Apache. + +.. _nginx-label: + +Nginx +***** + +This section covers two different ways of running Modoboa behind +`Nginx `_ using a WSGI application server. Choose +the one you prefer between `Green Unicorn `_ or +`uWSGI `_. + +In both cases, you'll need to download and `install nginx +`_. + +Green Unicorn +============= + +Firstly, `Download and install gunicorn +`_. Then, use the following sample +gunicorn configuration (create a new file named +:file:`gunicorn.conf.py` inside Modoboa's root dir):: + + backlog = 2048 + bind = "unix:/var/run/gunicorn/modoboa.sock" + pidfile = "/var/run/gunicorn/modoboa.pid" + daemon = True + debug = False + workers = 2 + logfile = "/var/log/gunicorn/modoboa.log" + loglevel = "info" + +To start gunicorn, execute the following commands:: + + $ cd + $ gunicorn -c gunicorn.conf.py .wsgi:application + +Now the nginx part. Just create a new virtual host and use the +following configuration:: + + upstream modoboa { + server unix:/var/run/gunicorn/modoboa.sock fail_timeout=0; + } + + server { + listen 443 ssl; + ssl on; + keepalive_timeout 70; + + server_name ; + root ; + + access_log /var/log/nginx/.access.log; + error_log /var/log/nginx/.error.log; + + ssl_certificate ; + ssl_certificate_key ; + + 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; + } + } + +If you do not plan to use SSL then change the listen directive to +``listen 80;`` and delete each of the following directives:: + + ssl on; + keepalive_timeout 70; + ssl_certificate ; + ssl_certificate_key ; + proxy_set_header X-Forwarded-Protocol ssl; + +If you do plan to use SSL, you'll have to generate a certificate and a +key. `This article +`__ +contains information about how to do it. + +Paste this content to your configuration (replace values between +``<>`` with yours) and restart nginx. + +uWSGI +===== + +The following setup is meant to get you started quickly. You should +read the documentation of both nginx and uwsgi to understand how to +optimize their configuration for your site. + +The Django documentation includes the following warning regarding +uwsgi: + +.. warning:: + + Some distributions, including Debian and Ubuntu, ship an outdated + version of uWSGI that does not conform to the WSGI + specification. Versions prior to 1.2.6 do not call close on the + response object after handling a request. In those cases the + request_finished signal isn’t sent. This can result in idle + connections to database and memcache servers. + +Use uwsgi 1.2.6 or newer. If you do not, you *will* run into +problems. Modoboa will fail in obscure ways. + +To use this setup, first `download and install uwsgi +`_. + +Here is a sample nginx configuration:: + + server { + listen 443 ssl; + ssl on; + keepalive_timeout 70; + + server_name ; + root ; + + ssl_certificate ; + ssl_certificate_key ; + + access_log /var/log/nginx/.access.log; + error_log /var/log/nginx/.error.log; + + location /sitestatic/ { + autoindex on; + alias ; + } + + # Whether or not Modoboa uses a media directory depends on how + # you configured Modoboa. It does not hurt to have this. + location /media/ { + autoindex on; + alias ; + } + + # This denies access to any file that begins with + # ".ht". Apache's .htaccess and .htpasswd are such files. A + # Modoboa installed from scratch would not contain any such + # files, but you never know what the future holds. + location ~ /\.ht { + deny all; + } + + location / { + include uwsgi_params; + uwsgi_pass ; + uwsgi_param UWSGI_SCRIPT .wsgi:application; + uwsgi_param UWSGI_SCHEME https; + } + } + +```` must be replaced by the value you used +when :ref:`you deployed your instance `. + +If you do not plan to use SSL then change the listen directive to +``listen 80;`` and delete each of the following directives:: + + ssl on; + keepalive_timeout 70; + ssl_certificate ; + ssl_certificate_key ; + uwsgi_param UWSGI_SCHEME https; + +If you do plan to use SSL, you'll have to generate a certificate and a +key. `This article +`_ +contains information about how to do it. + +Make sure to replace the ``<...>`` in the sample configuration with +appropriate values. Here are some explanations for the cases that may +not be completely self-explanatory: + +```` + Where Modoboa's :file:`settings.py` resides. This is also where the + :file:`sitestatic` and :file:`media` directories reside. + +```` + This is the URL which will be the root of your Modoboa site at your + domain. For instance, if your Modoboa installation is reachable at + at ``https://foo/modoboa`` then ```` is + ``/modoboa``. In this case you probably also have to set the + ``alias`` directives to point to where Modoboa's sitestatic and + media directories are because otherwise nginx won't be able to find + them. + + If Modoboa is at the root of your domain, then ```` is an empty string and can be deleted from the configuration + above. In this case, you probably do not need the ``alias`` + directives. + +```` + The location where uwsig is listening. It could be a unix domain + socket or an address:port combination. Ubuntu configures uwsgi so + that the port is:: + + unix:/run/uwsgi/app//socket + + where ```` is the name of the application. + +Your uwsgi configuration should be:: + + [uwsgi] + # Not needed when using uwsgi from pip + # plugins = python + chdir = + module = .wsgi:application + master = true + harakiri = 60 + processes = 4 + vhost = true + no-default-app = true + +The plugins directive should be turned on if you use a uwsgi +installation that requires it. If uwsgi was installed from pip, it +does not require it. In the configuration above: + +```` + The directory where :file:`manage.py` resides. This directory is the + parent of ```` + +```` + The name that you passed to ``modoboa-admin.py deploy`` when you + created your Modoboa instance. diff --git a/doc/upgrade.rst b/doc/upgrade.rst new file mode 100644 index 000000000..832c74d48 --- /dev/null +++ b/doc/upgrade.rst @@ -0,0 +1,336 @@ +####### +Upgrade +####### + +.. warning:: + + The new version you are going to install may need to modify your + database. Before you start, make sure to backup everything! + +Most of the time, upgrading your installation to a newer Modoboa +version only requires a few actions. In any case, you will need to +apply the general procedure first and then check if the version you +are installing requires specific actions. + +.. note:: + + In case you use a dedicated user and/or a virtualenv, do not forget to + use them: + + .. sourcecode:: bash + + > sudo -i + > source /bin/activate + +The general procedure is as follows:: + + > pip install modoboa== + > cd + > python manage.py migrate + > python manage.py collectstatic + +Once done, check if the version you are installing requires +:ref:`specific_upgrade_instructions`. + +Finally, restart your web server. + +.. _specific_upgrade_instructions: + +Specific instructions +********************* + +1.6.0 +===== + +An interesting feature brougth by this version is the capability to +make different checks about MX records. For example, Modoboa can +query main `DNSBL `_ providers +for every defined domain. With this, you will quickly now if one the +domains you manage is listed or not. To activate it, add the +following line to your crontab:: + + */30 * * * * /manage.py modo check_mx + +The communication with Modoboa public API has been reworked. Instead +of sending direct synchronous queries (for example to check new +versions), a cron job has been added. To activate it, add the +following line to your crontab:: + + 0 * * * * /manage.py communicate_with_public_api + +Please also note that public API now uses TLS so you must update your +configuration as follows:: + + MODOBOA_API_URL = 'https://api.modoboa.org/1/' + +1.5.0 +===== + +The API has been greatly improved and a documentation is now +available. To enable it, add ``'rest_framework_swagger'`` to the +``INSTALLED_APPS`` variable in :file:`settings.py` as follows:: + + INSTALLED_APPS = ( + 'django.contrib.auth', + 'django.contrib.contenttypes', + 'django.contrib.sessions', + 'django.contrib.messages', + 'django.contrib.sites', + 'django.contrib.staticfiles', + 'reversion', + 'rest_framework.authtoken', + 'rest_framework_swagger', + ) + +Then, add the following content into :file:`settings.py`, just after +the ``REST_FRAMEWORK`` variable:: + + SWAGGER_SETTINGS = { + "is_authenticated": False, + "api_version": "1.0", + "exclude_namespaces": [], + "info": { + "contact": "contact@modoboa.com", + "description": ("Modoboa API, requires a valid token."), + "title": "Modoboa API", + } + } + +You're done. The documentation is now available at the following address: + + http:///docs/api/ + +Finally, if you find a ``TEMPLATE_CONTEXT_PROCESSORS`` variable in +your :file:`settings.py` file, make sure it looks like this:: + + TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + [ + 'modoboa.core.context_processors.top_notifications', + ] + +1.4.0 +===== + +.. warning:: + + Please make sure to use Modoboa 1.3.5 with an up-to-date database + before an upgrade to 1.4.0. + +.. warning:: + + Do not follow the regular upgrade procedure for this version. + +Some extension have been moved back into the main repository. The main +reason for that is that using Modoboa without them doesn't make sense. + +First of all, you must rename the following applications listed inside +the ``MODOBOA_APPS`` variable: + ++--------------------------+--------------------+ +|Old name |New name | ++==========================+====================+ +|modoboa_admin |modoboa.admin | ++--------------------------+--------------------+ +|modoboa_admin_limits |modoboa.limits | ++--------------------------+--------------------+ +|modoboa_admin_relaydomains|modoboa.relaydomains| ++--------------------------+--------------------+ + +Then, apply the following steps: + +#. Uninstall old extensions:: + + $ pip uninstall modoboa-admin modoboa-admin-limits modoboa-admin-relaydomains + +#. Install all extension updates using pip (check the *Modoboa > Information* page) + +#. Manually migrate database:: + + $ cd + $ python manage.py migrate auth + $ python manage.py migrate admin 0001 --fake + $ python manage.py migrate admin + $ python manage.py migrate limits 0001 --fake + $ python manage.py migrate relaydomains 0001 --fake + $ python manage.py migrate + +#. Finally, update static files:: + + $ python manage.py collectstatic + +This version also introduces a REST API. To enable it: + +#. Add ``'rest_framework.authtoken'`` to the ``INSTALLED_APPS`` variable + +#. Add the following configuration inside ``settings.py``:: + + # Rest framework settings + + REST_FRAMEWORK = { + 'DEFAULT_AUTHENTICATION_CLASSES': ( + 'rest_framework.authentication.TokenAuthentication', + ), + 'DEFAULT_PERMISSION_CLASSES': ( + 'rest_framework.permissions.IsAuthenticated', + ) + } + +#. Run the following command:: + + $ python manage.py migrate + +1.3.5 +===== + +To enhance security, Modoboa now checks the `strength of user +passwords _`. + +To use this feature, add the following configuration into the ``settings.py`` file:: + + # django-passwords + + PASSWORD_MIN_LENGTH = 8 + + PASSWORD_COMPLEXITY = { + "UPPER": 1, + "LOWER": 1, + "DIGITS": 1 + } + + +1.3.2 +===== + +Modoboa now uses the *atomic requests* mode to preserve database +consistency (`reference +`_). + +To enable it, update the ``DATABASES`` variable in ``settings.py`` as +follows:: + + DATABASES = { + "default": { + # stuff before... + "ATOMIC_REQUESTS": True + }, + "amavis": { + # stuff before... + "ATOMIC_REQUESTS": True + } + } + +1.3.0 +===== + +This release does not bring awesome new features but it is a necessary +bridge to the future of Modoboa. All extensions now have their own git +repository and the deploy process has been updated to reflect this +change. + +Another important update is the use of Django 1.7. Besides its new +features, the migration system has been reworked and is now more +robust than before. + +Before we begin with the procedure, here is a table showing old +extension names and their new name: + ++----------------------------------------+--------------------------+--------------------------+ +|Old name |New package name |New module name | ++========================================+==========================+==========================+ +|modoboa.extensions.admin |modoboa-admin |modoboa_admin | ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.limits |modoboa-admin-limits |modoboa_admin_limits | ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.postfix_autoreply |modoboa-postfix-autoreply |modoboa_postfix_autoreply | ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.postfix_relay_domains|modoboa-admin-relaydomains|modoboa_admin_relaydomains| ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.radicale |modoboa-radicale |modoboa_radicale | ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.sievefilters |modoboa-sievefilters |modoboa_sievefilters | ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.stats |modoboa-stats |modoboa_stats | ++----------------------------------------+--------------------------+--------------------------+ +|modoboa.extensions.webmail |modoboa-webmail |modoboa_webmail | ++----------------------------------------+--------------------------+--------------------------+ + +Here are the required steps: + +#. Install the extensions using pip (look at the second column in the table above):: + + $ pip install + +#. Remove ``south`` from ``INSTALLED_APPS`` + +#. Rename old extension names inside ``MODOBOA_APPS`` (look at the third column in the table above) + +#. Remove ``modoboa.lib.middleware.ExtControlMiddleware`` from ``MIDDLEWARE_CLASSES`` + +#. Change ``DATABASE_ROUTERS`` to:: + + DATABASE_ROUTERS = ["modoboa_amavis.dbrouter.AmavisRouter"] + +#. Run the following commands:: + + $ cd + $ python manage.py migrate + +#. Reply ``yes`` to the question + +#. Run the following commands:: + + $ python manage.py load_initial_data + $ python manage.py collectstatic + +#. The cleanup job has been renamed in Django, so you have to modify your crontab entry:: + + - 0 0 * * * /manage.py cleanup + + 0 0 * * * /manage.py clearsessions + +1.2.0 +===== + +A new notification service let administrators know about new Modoboa +versions. To activate it, you need to update the +``TEMPLATE_CONTEXT_PROCESSORS`` variable like this:: + + from django.conf import global_settings + + TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + ( + 'modoboa.core.context_processors.top_notifications', + ) + +and to define the new ``MODOBOA_API_URL`` variable:: + + MODOBOA_API_URL = 'http://api.modoboa.org/1/' + +The location of external static files has changed. To use them, add a +new path to the ``STATICFILES_DIRS``:: + + # Additional locations of static files + STATICFILES_DIRS = ( + # Put strings here, like "/home/html/static" or "C:/www/django/static". + # Always use forward slashes, even on Windows. + # Don't forget to use absolute paths, not relative paths. + "/bower_components", + ) + +Run the following commands to define the hostname of your instance:: + + $ cd + $ python manage.py set_default_site + +If you plan to use the Radicale extension: + +#. Add ``'modoboa.extensions.radicale'`` to the ``MODOBOA_APPS`` variable + +#. Run the following commands:: + + $ cd + $ python manage.py syncdb + +.. warning:: + + You also have to note that the :file:`sitestatic` directory has moved from + ```` to ```` (it's probably + the parent directory). You have to adapt your web server configuration + to reflect this change.