github-jwinterm/modoboa
1
0
Fork 0
mirror of https://github.com/jwinterm/modoboa.git synced 2026-10-17 05:41:25 +02:00
Code Issues Packages Projects Releases Wiki Activity

Refactored documentation.

Browse Source
This commit is contained in:
Antoine Nguyen
2016-10-18 17:28:34 +02:00
parent 3decd518ad
commit e4e4e4c53c
27 changed files with 451 additions and 1182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.rst
+1 -19
View File
@@ -1,19 +1 @@
Contributions are always welcome but please try to follow those few rules:
- Modoboa tries to respect the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_.
- If you add some code, add some tests too. You can run the tests
suite locally by using `tox <https://testrun.org/tox/latest/config.html>`_
There are also a few commands that can help you to contribute:
Start a basic Modoboa instance with a few fixture::
$ tox -e serve
You can log in with admin/password.
Build the docs to see your changes::
$ tox -e doc
$ firefox .tox/doc/tmp/html/index.html
.. include:: doc/contributing.rst
doc/_static/api_access_form.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

doc/_static/modoboa_logo.png
Vendored
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

doc/additional/migrating.rst
-15
View File
@@ -1,15 +0,0 @@
###################
Tools for migration
###################
******************************
Migrate existing IMAP accounts
******************************
`OfflineIMAP extension <https://github.com/modoboa/modoboa-imap-migration>`_.
************
PostfixAdmin
************
`Official repository <https://github.com/modoboa/modoboa-pfxadmin-migrate>`_.
doc/conf.py
+1 -1
View File
@@ -127,7 +127,7 @@ else:
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['.static']
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
doc/getting_started/configuration.rst → doc/configuration.rst
View File
doc/contributing.rst
+29 -3
View File
@@ -1,4 +1,30 @@
Rules
=================
#################
How to contribute
#################
.. include:: ../CONTRIBUTING.rst
Contributions are always welcome but please try to follow those few rules:
- Modoboa tries to respect the `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_
- If you add some code, add some tests too. You can run the tests
suite locally by using `tox <https://testrun.org/tox/latest/config.html>`_
There are also a few commands that can help you to contribute:
Start a basic Modoboa instance with a few fixture::
$ tox -e serve
You can log in with admin/password.
Build the docs to see your changes::
$ tox -e doc
$ firefox .tox/doc/tmp/html/index.html
.. toctree::
contributing/getting_started
contributing/plugin_api
contributing/events
doc/extending/events.rst → doc/contributing/events.rst
View File
doc/extending/getting_started.rst → doc/contributing/getting_started.rst
View File
doc/extending/plugin_api.rst → doc/contributing/plugin_api.rst
View File
doc/getting_started/install.rst
-200
View File
@@ -1,200 +0,0 @@
.. _installation:
############
Installation
############
*****************
For the lazy ones
*****************
If you are in a hurry, you will love the `modoboa installer
<https://github.com/modoboa/modoboa-installer>`_! It's a set of Python
scripts to install a fully functional email server on one machine
(modoboa, postfix, dovecot, amavis and more).
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 <mail server hostname>
Wait a few minutes and you're done \o/
If you have more time or if you are just curious, you can install
Modoboa *the old way* by going to the next section.
************
Requirements
************
* `Python version 2.7+ <http://python.org/>`_
* `Django version 1.7+ <http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_
* `lxml python module <http://lxml.de/installation.html>`_
* `pycrypto python module <http://www.dlitz.net/software/pycrypto/>`_
* `rrdtool python binding <http://oss.oetiker.ch/rrdtool/>`_
* `sievelib python module <http://pypi.python.org/pypi/sievelib>`_
* `chardet python module <http://pypi.python.org/pypi/chardet>`_
* `argparse python module <http://pypi.python.org/pypi/argparse>`_
* `reversion python module <https://github.com/etianen/django-reversion>`_
.. _get_modoboa:
***********
Get Modoboa
***********
You can choose between two options:
* Use the Python package available on the `PyPI <http://pypi.python.org/pypi>`_
* Download the sources tarball
The easiest one is to install it from PyPI. Just run the following
command and you're done::
$ pip install modoboa
If you prefer to use the tarball, download the latest one and run the
following procedure::
$ tar xzf modoboa-<version>.tar.gz
$ cd modoboa-<version>
$ python setup.py install
All dependencies will be installed regardless the way you chose. The
only exception concerns the RRDtool binding because there isn't any
python package available, it is directly provided with the official
tarball.
Fortunately, all major distributions include a ready-to-use
package. On Debian/Ubuntu::
$ apt-get install libcairo2-dev libpango1.0-dev librrd-dev
$ apt-get install python-rrdtool
`virtualenv <http://www.virtualenv.org/en/latest/>`_ users
==========================================================
When you deploy an application using virtualenv, you may have to
compile some dependencies. For example, modoboa relies on lxml,
which is a C python module. In order to install it, you will need to
install the following requirements:
* python development files
* libxslt development files
* libxml2 development files
* libz development files
On a Debian like system, just run the following command::
$ apt-get install python-dev libxml2-dev libxslt-dev zlib1g-dev
.. _database:
********
Database
********
Thanks to Django, Modoboa supports several databases. Depending on
the one you will use, you must install the appropriate python package:
* `mysqldb <http://mysql-python.sourceforge.net/>`_ for `MySQL <http://www.mysql.com>`_
* `psycopg2 <http://initd.org/psycopg/>`_ for `PostgreSQL <http://www.postgresql.org>`_
Then, create a user and a database that will be used by Modoboa. Make
sure your database is using UTF8 as a default charset.
.. _deployment:
**********
Deployment
**********
`modoboa-admin.py`, a command line tool, lets you deploy a
*ready-to-use* Modoboa site using only one instruction::
$ modoboa-admin.py deploy modoboa_example --collectstatic [--dburl default:database-url] [--extensions extensions]
.. note::
By default, the core application of Modoboa and some necessary plugins
(admin, relaydomains and limits) are installed. To install extensions,
use the ``--extensions`` option which accepts a list of extension names
as argument (``--extensions ext1 ext2 ...``).
If you want to install all extensions, just use the ``all``
shortcut 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 plugins can be found on the :doc:`index page
<../index>`. Instructions to install them are available on each plugin 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
<http://modoboa-amavis.readthedocs.org>`_ extension, use the
``amavis:`` prefix. An example two connections: ``--dburl
default:<database url> amavis:<database url>``.
Your database url should meet the following syntax
``scheme://[user:pass@][host:port]/dbname`` **OR**
``sqlite:////full/path/to/your/database/file.sqlite``.
Available schemes are:
* postgres
* postgresql
* postgis
* mysql
* mysql2
* 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 see the complete option list by running the following command::
$ modoboa-admin.py help deploy
.. note::
If you plan to serve Modoboa using a URL prefix, you must change the
value of the ``LOGIN_URL`` parameter to ``LOGIN_URL = '/<prefix>/accounts/login/'``.
.. _first_use:
*********
First use
*********
Your installation should now have a default super administrator:
* Username: ``admin``
* Password: ``password``
It is **strongly** recommended to change this password the first time
you log into Modoboa.
To check if your installation works, just launch the embedded HTTP
server::
$ python manage.py runserver
You should be able to access Modoboa at http://localhost:8000/.
For a fully working interface using the embedded HTTP server, you need
to set the ``DEBUG`` parameter in settings.py to ``True``.
For a production environment, we recommend using a stable webserver
like :ref:`apache2` or :ref:`nginx-label`. Don't forget to set
``DEBUG`` back to ``False``.
doc/getting_started/upgrade.rst
-301
View File
@@ -1,301 +0,0 @@
##################################
Upgrading an existing installation
##################################
This section contains all the upgrade procedures required to use
newest versions of Modoboa.
.. note::
Before running a migration, we recommend that you make
a copy of your existing database.
.. _latestversion:
**************
Latest version
**************
Fetch the latest version (see :ref:`get_modoboa`) and install
it. ``pip`` users, just run the following command::
$ pip install modoboa==<VERSION>
Replace ``<VERSION>`` by the appropriate value.
As for a fresh installation, ``modoboa-admin.py`` can be used to
upgrade your local configuration. To do so, remove the directory where
your instance was first deployed::
$ rm -rf <modoboa_instance_dir>
.. warning::
If you customized your configuration file (:file:`settings.py`) with
non-standard settings, you'll have to re-apply them.
Finally, run the ``deploy`` comamand. Make sure to consult the
:ref:`deployment` section to know more about the available options.
If you prefer the manual way, check if
:ref:`specific_upgrade_instructions` are required according to the
version you're installing.
To finish, restart the web server process according to the environment
you did choose. See :ref:`webservers` for more details.
1.1.7: manual learning for SpamAssassin
=======================================
A new feature allows administrators and users to manually train
SpamAssassin in order to customize its behaviour.
Check :ref:`amavis:sa_manual_learning` to know more about this feature.
1.1.6: Few bugfixes
===================
Catchall aliases were not really functional until this version as they
were eating all domain traffic.
To fix them, a postfix map file (``sql-mailboxes-self-aliases.cf``)
has been re-introduced and must be listed into the
``virtual_alias_maps`` setting. See :ref:`postfix_config` for the
order.
1.1.2: Audit trail issues
=========================
Update the :file:`settings.py` file as follows:
#. Remove the ``'reversion.middleware.RevisionMiddleware'``
middleware from the ``MIDDLEWARE_CLASSES`` variable
#. Add the new ``'modoboa.lib.middleware.RequestCatcherMiddleware'``
middleware at the end of the ``MIDDLEWARE_CLASSES`` variable
1.1.1: Few bugfixes
===================
For those who installed Dovecot in a non-standard location, it is now
possible to tell Modoboa where to find it. Just define a variable
named ``DOVECOT_LOOKUP_PATH`` in the :file:`settings.py` file and
include the appropriate lookup path inside::
DOVECOT_LOOKUP_PATH = ("/usr/sbin/dovecot", "/usr/local/sbin/dovecot")
.. _1.1.0:
1.1.0: relay domains and better passwords encryption
====================================================
Due to code refactoring, some modifications need to be done into
:file:`settings.py`:
#. ``MODOBOA_APPS`` must contain the following applications::
MODOBOA_APPS = (
'modoboa',
'modoboa.core',
'modoboa.lib',
'modoboa.extensions.admin',
'modoboa.extensions.limits',
'modoboa.extensions.postfix_autoreply',
'modoboa.extensions.webmail',
'modoboa.extensions.stats',
'modoboa.extensions.amavis',
'modoboa.extensions.sievefilters',
)
#. Add ``'modoboa.extensions.postfix_relay_domains'`` to
``MODOBOA_APPS``, just before
``'modoboa.extensions.limits'``
#. ``AUTH_USER_MODEL`` must be set to ``core.User``
#. Into ``LOGGING``, replace ``modoboa.lib.logutils.SQLHandler`` by
``modoboa.core.loggers.SQLHandler``
Then, run the following commands to migrate your installation::
$ python manage.py syncdb
$ python manage.py migrate core 0001 --fake
$ python manage.py migrate
$ python manage.py collectstatic
Finally, update both :ref:`Dovecot <dovecot_authentication>` and
:ref:`Postfix <postfix>` queries.
1.0.1: operations on mailboxes
==============================
The way Modoboa handles **rename** and **delete** operations on
mailboxes has been improved. Make sure to consult :ref:`fs_operations`
and :ref:`Postfix configuration <postfix_config>`. Look at the
``smtpd_recipient_restrictions`` setting.
Run ``modoboa-admin.py postfix_maps --dbtype <mysql|postgres|sqlite>
<tempdir>`` and compare the files with those that postfix currently
use. Make necessary updates in light of the differences
1.0.0: production ready, at last
================================
Configuration file update
-------------------------
Several modifications need to be done into :file:`settings.py`.
#. Add the following import statement::
from logging.handlers import SysLogHandler
#. Set the ``ALLOWER_HOSTS`` variable::
ALLOWED_HOSTS = [
'<your server fqdn>',
]
#. Activate the ``django.middleware.csrf.CsrfViewMiddleware``
middleware and add the ``reversion.middleware.RevisionMiddleware``
middleware to ``MIDDLEWARE_CLASSES`` like this::
MIDDLEWARE_CLASSES = (
'django.middleware.common.CommonMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.locale.LocaleMiddleware',
# Uncomment the next line for simple clickjacking protection:
# 'django.middleware.clickjacking.XFrameOptionsMiddleware',
'reversion.middleware.RevisionMiddleware',
'modoboa.lib.middleware.AjaxLoginRedirect',
'modoboa.lib.middleware.CommonExceptionCatcher',
'modoboa.lib.middleware.ExtControlMiddleware',
)
#. Add the ``reversion`` application to ``INSTALLED_APPS``
#. Remove all modoboa's application from ``INSTALLED_APPS`` and put
them into the new ``MODOBOA_APPS`` variable like this::
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.sites',
'django.contrib.messages',
'django.contrib.staticfiles',
'south',
'reversion',
)
# A dedicated place to register Modoboa applications
# Do not delete it.
# Do not change the order.
MODOBOA_APPS = (
'modoboa',
'modoboa.auth',
'modoboa.admin',
'modoboa.lib',
'modoboa.userprefs',
'modoboa.extensions.limits',
'modoboa.extensions.postfix_autoreply',
'modoboa.extensions.webmail',
'modoboa.extensions.stats',
'modoboa.extensions.amavis',
'modoboa.extensions.sievefilters',
)
INSTALLED_APPS += MODOBOA_APPS
#. Set the ``AUTH_USER_MODEL`` variable like this::
AUTH_USER_MODEL = 'admin.User'
#. Modify the logging configuration as follows::
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'filters': {
'require_debug_false': {
'()': 'django.utils.log.RequireDebugFalse'
}
},
'formatters': {
'syslog': {
'format': '%(name)s: %(levelname)s %(message)s'
},
},
'handlers': {
'mail_admins': {
'level': 'ERROR',
'filters': ['require_debug_false'],
'class': 'django.utils.log.AdminEmailHandler'
},
'console': {
# logging handler that outputs log messages to terminal
'class': 'logging.StreamHandler',
#'level': 'DEBUG', # message level to be written to console
},
'syslog-auth': {
'class': 'logging.handlers.SysLogHandler',
'facility': SysLogHandler.LOG_AUTH,
'formatter': 'syslog'
},
'modoboa': {
'class': 'modoboa.lib.logutils.SQLHandler',
}
},
'loggers': {
'django.request': {
'handlers': ['mail_admins'],
'level': 'ERROR',
'propagate': True,
},
'modoboa.auth': {
'handlers': ['syslog-auth', 'modoboa'],
'level': 'INFO',
'propagate': False
},
'modoboa.admin': {
'handlers': ['modoboa'],
'level': 'INFO',
'propagate': False
}
}
}
Postfix and Dovecot configuration update
----------------------------------------
It is necessary to update the queries used to retrieve users and mailboxes:
#. Run ``modoboa-admin.py postfix_maps --dbtype <mysql|postgres> <tempdir>`` and compare the files with those that postfix currently
use. Make necessary updates in light of the differences
#. Into :file:`dovecot-sql.conf`, update the ``user_query`` query, refer to
:ref:`dovecot_mysql_queries` or :ref:`dovecot_pg_queries`
#. Update dovecot's configuration to activate the new :ref:`quota related features <dovecot_quota>`
Migration issues
----------------
When running the ``python manage.py syncdb --migrate`` command, you
may encounter the following issues:
#. Remove useless content types
If the script asks you this question, just reply **no**.
#. South fails to migrate ``reversion``
Due to the admin user model change, the script :file:`0001_initial.py`
may fail. Just deactivate ``reversion`` from ``INSTALLED_APPS`` and
run the command again. Once done, reactivate ``reversion`` and run
the command one last time.
doc/index.rst
+62 -59
View File
@@ -3,70 +3,73 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Modoboa's documentation!
========================
Modoboa documentation
=====================
***************
Getting started
***************
.. image:: _static/modoboa_logo.png
:align: center
Overview
--------
Modoboa is a mail hosting and management platform including a modern
and simplified Web User Interface designed to work with `Postfix
<http://www.postfix.org>`_ and `Dovecot <http://www.dovecot.org>`_.
It is extensible by nature and comes with a lot of additional extensions:
+------------------------------------------------+-------------------------+------------------------------------------------------+
|Name |Description |Documentation |
| | | |
| | | |
| | | |
+================================================+=========================+======================================================+
|`modoboa-amavis |A frontend for `Amavis |https://modoboa-amavis.readthedocs.io |
|<https://github.com/modoboa-amavis>`_ |<http://www.amavis.org>`_| |
| | | |
| | | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-dmarc |A set of tools to use |https://github.com/modoboa-dmarc |
|<https://github.com/modoboa-dmarc>`_ |`DMARC | |
| |<https://dmarc.org>`_ | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-imap-migration |Migrate mailboxes from an|https://github.com/modoboa-imap-migration |
|<https://github.com/modoboa-imap-migration>`_ |existing server using | |
| |IMAP (and offlineimap) | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-pdfcredentials |Generate PDF documents |https://github.com/modoboa-pdfcredentials |
|<https://github.com/modoboa-pdfcredentials>`_ |containing account | |
| |credentials | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-pfxadmin-migrate |A tool to migrate from |https://github.com/modoboa/modoboa-pfxadmin-migrate |
|<https://github.com/modoboa-pfxadmin-migrate>`_ |Postfixadmin | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-postfix-autoreply |Away message editor |https://modoboa-postfix-autoreply.readthedocs.io |
|<https://github.com/modoboa-postfix-autoreply>`_|(postfix compatible) | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-radicale |A frontend for `Radicale |https://modoboa-radicale.readthedocs.io |
|<https://github.com/modoboa-radicale>`_ |<http://radicale.org>`_ | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-sievefilters |A Sieve filters (rules) |https://modoboa-sievefilters.readthedocs.io |
|<https://github.com/modoboa-sievefilters>`_ |editor | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-stats |Graphical statistics |https://modoboa-stats.readthedocs.io |
|<https://github.com/modoboa-stats>`_ |(message traffic and | |
| |more) | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
|`modoboa-webmail |A simple webmail |https://modoboa-webmail.readthedocs.io |
|<https://github.com/modoboa-webmail>`_ | | |
+------------------------------------------------+-------------------------+------------------------------------------------------+
Table of contents
-----------------
.. toctree::
:maxdepth: 2
:maxdepth: 1
installation
upgrade
getting_started/configuration
*******
Plugins
*******
.. toctree::
:maxdepth: 2
plugins/amavis
plugins/statistics
plugins/radicale
plugins/postfix_autoreply
plugins/sievefilters
plugins/webmail
********************************
Integration with other softwares
********************************
.. toctree::
:maxdepth: 2
integration/imap_and_smtp
integration/web_servers
*****************
Extending Modoboa
*****************
.. toctree::
:maxdepth: 2
extending/getting_started
extending/plugin_api
extending/events
*******************
Additional resource
*******************
.. toctree::
:maxdepth: 2
additional/migrating
*******************
Contributing
*******************
.. toctree::
:maxdepth: 2
configuration
rest_api
contributing
contributors
doc/installation.rst
+28 -422
View File
@@ -2,13 +2,13 @@
Installation
############
Using the installer
===================
Recommanded way
===============
If you start from scratch and want to deploy a complete mail server,
you will love the `modoboa installer
<https://github.com/modoboa/modoboa-installer>`_! It is the easiest
and the quickest way to setup a fully functional server (modooba,
and the quickest way to setup a fully functional server (modoboa,
postfix, dovecot, amavis and more) on one machine.
.. warning::
@@ -16,7 +16,7 @@ postfix, dovecot, amavis and more) on one machine.
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`.
:ref:`manually <by_hand>`.
To use it, just run the following commands in your terminal:
@@ -30,434 +30,40 @@ Wait a few minutes and you're done \o/
.. _by_hand:
By hand
=======
Manual installation
===================
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.
For those who need a manual installation or who just want to setup a
specific part, here are the steps you must follow:
Prepare the system
------------------
.. toctree::
:maxdepth: 1
First of all, we recommand the following context:
manual_installation/modoboa
manual_installation/webserver
manual_installation/dovecot
manual_installation/postfix
* Use a dedicated system user
* Use a `virtualenv <http://www.virtualenv.org/en/latest/>`_ 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 <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 :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
<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``.
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
Extensions
----------
.. note::
Only few commands are needed to add a new extension to your setup.
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.
In case you use a dedicated user and/or a virtualenv, do not forget to
use them:
.. _apache2:
.. sourcecode:: bash
Apache2
*******
> sudo -i <modoboa_user>
> source <virtuenv_path>/bin/activate
First, make sure that ``mod_wsgi`` is installed on your server.
Then, run the following commands:
Create a new virtualhost in your Apache configuration and put the
following content inside::
.. sourcecode:: bash
<VirtualHost *:80>
ServerName <your value>
DocumentRoot <modoboa_instance_path>
> pip install <EXTENSION>==<VERSION>
> cd <modoboa_instance_dir>
> python manage.py migrate
> python manage.py collectstatic
Alias /media/ <modoboa_instance_path>/media/
<Directory <modoboa_instance_path>/media>
Order deny,allow
Allow from all
</Directory>
Alias /sitestatic/ <modoboa_instance_path>/sitestatic/
<Directory <modoboa_instance_path>/sitestatic>
Order deny,allow
Allow from all
</Directory>
WSGIScriptAlias / <modoboa_instance_path>/<instance_name>/wsgi.py
</VirtualHost>
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=<modoboa_instance>:<virtualenv path>/lib/python2.7/site-packages
WSGIProcessGroup example.com
Replace values between ``<>`` with yours. If you don't use a
`virtualenv <http://virtualenv.readthedocs.org/en/latest/>`_, 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 <http://nginx.org/>`_ using a WSGI application server. Choose
the one you prefer between `Green Unicorn <http://gunicorn.org/>`_ or
`uWSGI <https://github.com/unbit/uwsgi>`_.
In both cases, you'll need to download and `install nginx
<http://wiki.nginx.org/Install>`_.
Green Unicorn
=============
Firstly, `Download and install gunicorn
<http://gunicorn.org/install.html>`_. 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 <modoboa dir>
$ gunicorn -c gunicorn.conf.py <modoboa dir>.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 <host fqdn>;
root <modoboa_instance_path>;
access_log /var/log/nginx/<host fqdn>.access.log;
error_log /var/log/nginx/<host fqdn>.error.log;
ssl_certificate <ssl certificate for your site>;
ssl_certificate_key <ssl certificate key for your site>;
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 for your site>;
ssl_certificate_key <ssl certificate key for your site>;
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
<http://wiki.nginx.org/HttpSslModule#Generate_Certificates>`__
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
<http://uwsgi-docs.readthedocs.org/en/latest/WSGIquickstart.html>`_.
Here is a sample nginx configuration::
server {
listen 443 ssl;
ssl on;
keepalive_timeout 70;
server_name <host fqdn>;
root <modoboa's settings dir>;
ssl_certificate <ssl certificate for your site>;
ssl_certificate_key <ssl certificate key for your site>;
access_log /var/log/nginx/<host fqdn>.access.log;
error_log /var/log/nginx/<host fqdn>.error.log;
location <modoboa's root url>/sitestatic/ {
autoindex on;
alias <location of sitestatic on your file system>;
}
# Whether or not Modoboa uses a media directory depends on how
# you configured Modoboa. It does not hurt to have this.
location <modoboa's root url>/media/ {
autoindex on;
alias <location of media on your file system>;
}
# 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 <modoba's root url>/ {
include uwsgi_params;
uwsgi_pass <uwsgi port>;
uwsgi_param UWSGI_SCRIPT <modoboa instance name>.wsgi:application;
uwsgi_param UWSGI_SCHEME https;
}
}
``<modoboa instance name>`` must be replaced by the value you used
when :ref:`you deployed your instance <deployment>`.
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 for your site>;
ssl_certificate_key <ssl certificate key for your site>;
uwsgi_param UWSGI_SCHEME https;
If you do plan to use SSL, you'll have to generate a certificate and a
key. `This article
<http://wiki.nginx.org/HttpSslModule#Generate_Certificates>`_
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:
``<modoboa's settings dir>``
Where Modoboa's :file:`settings.py` resides. This is also where the
:file:`sitestatic` and :file:`media` directories reside.
``<modoboa's root url>``
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 ``<modoboa's root url>`` 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 ``<modoboa root
url>`` is an empty string and can be deleted from the configuration
above. In this case, you probably do not need the ``alias``
directives.
``<uwsgi port>``
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/<app name>/socket
where ``<app name>`` is the name of the application.
Your uwsgi configuration should be::
[uwsgi]
# Not needed when using uwsgi from pip
# plugins = python
chdir = <modoboa's top dir>
module = <name>.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:
``<modoboa's top dir>``
The directory where :file:`manage.py` resides. This directory is the
parent of ``<modoboa's settings dir>``
``<name>``
The name that you passed to ``modoboa-admin.py deploy`` when you
created your Modoboa instance.
Then, restart your web sever.
doc/integration/imap_and_smtp.rst → doc/manual_installation/dovecot.rst
+5 -75
View File
@@ -1,15 +1,11 @@
###################
Dovecot and Postfix
###################
.. _dovecot:
*******
#######
Dovecot
*******
#######
Modoboa works better with Dovecot 2.0 so the following documentation
is suitable for this combination.
Modoboa requires Dovecot 2+ to work so the following documentation is
suitable for this combination.
In this section, we assume dovecot's configuration resides in
:file:`/etc/dovecot`, all pathes will be relative to this directory.
@@ -403,70 +399,4 @@ Finally, configure the ``sieve`` plugin by editing the
Restart Dovecot.
.. _postfix:
*******
Postfix
*******
This section gives an example about building a simple virtual hosting
configuration with *Postfix*. Refer to the `official documentation
<http://www.postfix.org/VIRTUAL_README.html>`_ for more explanation.
Map files
=========
You first need to create configuration files (or map files) that will
be used by Postfix to lookup into Modoboa tables.
To automaticaly generate the requested map files and store them in a
directory, run the following command::
$ modoboa-admin.py postfix_maps --dbtype <mysql|postgres|sqlite> <directory>
``<directory>`` is the directory where the files will be
stored. Answer the few questions and you're done.
.. _postfix_config:
Configuration
=============
Use the following configuration in the :file:`/etc/postfix/main.cf` file
(this is just one possible configuration)::
# Stuff before
virtual_transport = lmtp:unix:private/dovecot-lmtp
relay_domains =
virtual_mailbox_domains = <driver>:/etc/postfix/sql-domains.cf
virtual_alias_domains = <driver>:/etc/postfix/sql-domain-aliases.cf
virtual_alias_maps = <driver>:/etc/postfix/sql-aliases.cf
relay_domains = <driver>:/etc/postfix/sql-relaydomains.cf
transport_maps =
<driver>:/etc/postfix/sql-spliteddomains-transport.cf
<driver>:/etc/postfix/sql-relaydomains-transport.cf
smtpd_recipient_restrictions =
# ...
check_recipient_access
<driver>:/etc/postfix/sql-maintain.cf
<driver>:/etc/postfix/sql-relay-recipient-verification.cf
permit_mynetworks
reject_unauth_destination
reject_unverified_recipient
# ...
smtpd_sender_login_maps =
<driver>:/etc/postfix/sql-sender-login-mailboxes.cf
<driver>:/etc/postfix/sql-sender-login-aliases.cf
smtpd_sender_restrictions =
reject_sender_login_mismatch
# Stuff after
Replace ``<driver>`` by the name of the database you use.
Restart Postfix.
Now, you can go to the :ref:`postfix` section to finish the installation.
doc/manual_installation/modoboa.rst
+140
View File
@@ -0,0 +1,140 @@
#######
Modoboa
#######
This section describes the installation of the web interface (a
`Django <https://www.djangoproject.com/>`_ project).
Prepare the system
------------------
First of all, we recommand the following context:
* Use a dedicated system user
* Use a `virtualenv <http://www.virtualenv.org/en/latest/>`_ 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 <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 :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
<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``.
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
Now you can continue to the :ref:`webserver` section.
doc/manual_installation/postfix.rst
+67
View File
@@ -0,0 +1,67 @@
.. _postfix:
#######
Postfix
#######
This section gives an example about building a simple virtual hosting
configuration with *Postfix*. Refer to the `official documentation
<http://www.postfix.org/VIRTUAL_README.html>`_ for more explanation.
Map files
=========
You first need to create configuration files (or map files) that will
be used by Postfix to lookup into Modoboa tables.
To automaticaly generate the requested map files and store them in a
directory, run the following command::
$ modoboa-admin.py postfix_maps --dbtype <mysql|postgres|sqlite> <directory>
``<directory>`` is the directory where the files will be
stored. Answer the few questions and you're done.
.. _postfix_config:
Configuration
=============
Use the following configuration in the :file:`/etc/postfix/main.cf` file
(this is just one possible configuration)::
# Stuff before
virtual_transport = lmtp:unix:private/dovecot-lmtp
relay_domains =
virtual_mailbox_domains = <driver>:/etc/postfix/sql-domains.cf
virtual_alias_domains = <driver>:/etc/postfix/sql-domain-aliases.cf
virtual_alias_maps = <driver>:/etc/postfix/sql-aliases.cf
relay_domains = <driver>:/etc/postfix/sql-relaydomains.cf
transport_maps =
<driver>:/etc/postfix/sql-spliteddomains-transport.cf
<driver>:/etc/postfix/sql-relaydomains-transport.cf
smtpd_recipient_restrictions =
# ...
check_recipient_access
<driver>:/etc/postfix/sql-maintain.cf
<driver>:/etc/postfix/sql-relay-recipient-verification.cf
permit_mynetworks
reject_unauth_destination
reject_unverified_recipient
# ...
smtpd_sender_login_maps =
<driver>:/etc/postfix/sql-sender-login-mailboxes.cf
<driver>:/etc/postfix/sql-sender-login-aliases.cf
smtpd_sender_restrictions =
reject_sender_login_mismatch
# Stuff after
Replace ``<driver>`` by the name of the database you use.
Restart Postfix.
doc/integration/web_servers.rst → doc/manual_installation/webserver.rst
+28 -35
View File
@@ -1,14 +1,8 @@
.. _webservers:
.. _webserver:
###########
Web servers
###########
.. _apache2:
*******
Apache2
*******
##########
Web server
##########
.. note::
@@ -19,31 +13,34 @@ Apache2
possible that **your** installation of uwsgi or nginx or Apache or
what-have-you works differently. Keep this in mind.
mod_wsgi
========
.. _apache2:
First, make sure that mod_wsgi is installed on your server.
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::
<VirtualHost *:80>
ServerName <your value>
DocumentRoot <path to your site's dir>
DocumentRoot <modoboa_instance_path>
Alias /media/ <path to your site's dir>/media/
<Directory <path to your site's dir>/media>
Alias /media/ <modoboa_instance_path>/media/
<Directory <modoboa_instance_path>/media>
Order deny,allow
Allow from all
</Directory>
Alias /sitestatic/ <path to your site's dir>/sitestatic/
<Directory <path to your site's dir>/sitestatic>
Alias /sitestatic/ <modoboa_instance_path>/sitestatic/
<Directory <modoboa_instance_path>/sitestatic>
Order deny,allow
Allow from all
</Directory>
WSGIScriptAlias / <path to your site's dir>/wsgi.py
WSGIScriptAlias / <modoboa_instance_path>/<instance_name>/wsgi.py
</VirtualHost>
This is just one possible configuration.
@@ -51,7 +48,7 @@ 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=<path to your site's dir>:<virtualenv path>/lib/python2.7/site-packages
WSGIDaemonProcess example.com python-path=<modoboa_instance>:<virtualenv path>/lib/python2.7/site-packages
WSGIProcessGroup example.com
Replace values between ``<>`` with yours. If you don't use a
@@ -59,24 +56,17 @@ Replace values between ``<>`` with yours. If you don't use a
remove the last part of the ``WSGIDaemonProcess`` directive.
.. note::
You will certainly need more configuration in order to launch
Apache.
Now, you can go the :ref:`dovecot` section to continue the installation.
.. _nginx-label:
*****
Nginx
*****
.. 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.
This section covers two different ways of running Modoboa behind
`Nginx <http://nginx.org/>`_ using a WSGI application server. Choose
the one you prefer between `Green Unicorn <http://gunicorn.org/>`_ or
@@ -86,7 +76,7 @@ In both cases, you'll need to download and `install nginx
<http://wiki.nginx.org/Install>`_.
Green Unicorn
=============
+++++++++++++
Firstly, `Download and install gunicorn
<http://gunicorn.org/install.html>`_. Then, use the following sample
@@ -120,7 +110,7 @@ following configuration::
keepalive_timeout 70;
server_name <host fqdn>;
root <modoboa's root dir>;
root <modoboa_instance_path>;
access_log /var/log/nginx/<host fqdn>.access.log;
error_log /var/log/nginx/<host fqdn>.error.log;
@@ -160,11 +150,12 @@ key. `This article
contains information about how to do it.
Paste this content to your configuration (replace values between
``<>`` with yours), restart nginx and enjoy a really fast
application!
``<>`` with yours) and restart nginx.
Now, you can go the :ref:`dovecot` section to continue the installation.
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
@@ -304,3 +295,5 @@ does not require it. In the configuration above:
``<name>``
The name that you passed to ``modoboa-admin.py deploy`` when you
created your Modoboa instance.
Now, you can go the :ref:`dovecot` section to continue the installation.
doc/plugins/amavis.rst
-7
View File
@@ -1,7 +0,0 @@
.. _amavis_frontend:
####################
Amavisd-new frontend
####################
`Official documentation <http://modoboa-amavis.readthedocs.org>`_.
doc/plugins/postfix_autoreply.rst
-7
View File
@@ -1,7 +0,0 @@
.. _postfix_ar:
###########################
Postfix auto-reply messages
###########################
`Official documentation <http://modoboa-postfix-autoreply.readthedocs.org>`_.
doc/plugins/radicale.rst
-5
View File
@@ -1,5 +0,0 @@
#################
Radicale frontend
#################
`Official documentation <http://modoboa-radicale.readthedocs.org>`_.
doc/plugins/sievefilters.rst
-5
View File
@@ -1,5 +0,0 @@
#############
Sieve filters
#############
`Official documentation <http://modoboa-sievefilters.readthedocs.org>`_.
doc/plugins/statistics.rst
-7
View File
@@ -1,7 +0,0 @@
.. _stats:
####################
Graphical statistics
####################
`Official documentation <http://modoboa-stats.readthedocs.org>`_.
doc/plugins/webmail.rst
-7
View File
@@ -1,7 +0,0 @@
.. _webmail:
#######
Webmail
#######
`Official documentation <http://modoboa-webmail.readthedocs.org>`_.
doc/rest_api.rst
+31
View File
@@ -0,0 +1,31 @@
########
REST API
########
To ease the integration with external sources (software or other),
Modoboa provides a REST API.
Every installed instance comes with a ready-to-use API and a
documentation. You will find them using the following url patterns:
* API: *http://<hostname>/api/v1/*
* Documentation: *http://<hostname>/docs/api/*
An `example <https://demo.modoboa.org/docs/api/>`_ of this
documentation is available on the official demo.
Using this API requires an authentication and for now, only a token
based authentication is supported. To get a valid token, log-in to
your instance with a super administrator, go to *Settings > API* and
activate the API access. Press the Update button and wait until the
page is reloaded, the token will be displayed.
.. image:: _static/api_access_form.png
:align: center
To make valid API calls, every requests you send must embed this token
within an Authorization HTTP header like this::
Authorization: Token <YOUR_TOKEN>
and the content type of those requests must be ``application/json``.
doc/upgrade.rst
+58 -13
View File
@@ -2,38 +2,83 @@
Upgrade
#######
Modoboa
*******
.. 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
version only requires a few actions. In every 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:
In case you use a dedicated user and/or a virtualenv, do not forget to
use them:
.. sourcecode:: bash
.. sourcecode:: bash
> sudo -i <modoboa_user>
> source <virtuenv_path>/bin/activate
> sudo -i <modoboa_user>
> source <virtuenv_path>/bin/activate
The general procedure is as follows::
Then, run the following commands:
> pip install modoboa==<VERSION>
> cd <modoboa_instance_dir>
> python manage.py migrate
> python manage.py collectstatic
.. sourcecode:: bash
> pip install modoboa==<VERSION>
> cd <modoboa_instance_dir>
> 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.
Sometimes, you might need to upgrade postfix map files too. To do so,
just run the ``generate_postfix_maps`` command on the same directory
than the one used for installation (:file:`/etc/postfix` by default).
Make sure to use root privileges and run the following command:
.. sourcecode:: bash
> python manage.py generate_postfix_maps --destdir <directory>
Then, reload postfix.
Extensions
**********
If a new version is available for an extension you're using, it is
recommanded to install it. Upgrading an extensions is pretty and the
procedure is almost the same than the one used for Modoboa.
In case you use a dedicated user and/or a virtualenv, do not forget to
use them:
.. sourcecode:: bash
> sudo -i <modoboa_user>
> source <virtuenv_path>/bin/activate
Then, run the following commands:
.. sourcecode:: bash
> pip install <EXTENSION>==<VERSION>
> cd <modoboa_instance_dir>
> python manage.py migrate
> python manage.py collectstatic
Finally, restart your web server.
It is a generic upgrade procedure which will be enough most of the
time but it is generally a good idea to check the associated
documentation.
.. _specific_upgrade_instructions:
Specific instructions
modoboa/core/forms.py
+1 -1
View File
@@ -97,7 +97,7 @@ class APIAccessForm(forms.Form):
"""Form to control API access."""
enable_api_access = forms.BooleanField(
label=_("Enable API access"), required=False)
label=ugettext_lazy("Enable API access"), required=False)
def __init__(self, *args, **kwargs):
"""Initialize form."""