mirror of
https://github.com/jwinterm/modoboa.git
synced 2026-10-18 05:51:26 +02:00
Merge pull request #947 from tonioo/refactor/documentation
Refactor/documentation
This commit is contained in:
Antoine Nguyen
+1
-19
@@ -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
|
||||
|
||||
Vendored
BIN
Binary file not shown.
|
After Width: | Height: | Size: 17 KiB |
Vendored
BIN
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
@@ -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>`_.
|
||||
@@ -1,74 +0,0 @@
|
||||
Using the virtual machine
|
||||
*************************
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
A virtual machine with a ready-to-use Modoboa setup is available `here
|
||||
<http://modoboa.org/resources/modoboa.vmdk.bz2>`_. It is composed of
|
||||
the following components:
|
||||
|
||||
* Debian 6.0 (squeeze)
|
||||
* Modoboa and its prerequisites
|
||||
* MySQL
|
||||
* Postfix
|
||||
* Dovecot
|
||||
* nginx and gunicorn
|
||||
|
||||
Actually, it is the result you obtain if you follow the official
|
||||
documentation.
|
||||
|
||||
The disk image is using the `VMDK
|
||||
<http://en.wikipedia.org/wiki/VMDK>`_ format and is compressed using
|
||||
bzip2. To decompress it, just run the following command::
|
||||
|
||||
$ bunzip2 modoboa.vmdk.bz2
|
||||
|
||||
If you can't use the vmdk format, you can use `qemu
|
||||
<http://qemu.org/>`_ to convert it to another one. For example::
|
||||
|
||||
$ qemu-img convert modoboa.vmdk -O qcow2 modoboa.qcow2
|
||||
|
||||
Then, just use your prefered virtualization software (qemu, kvm,
|
||||
virtualbox, etc.) to start the machine. You'll need to configure at
|
||||
least one bridged network interface if you want to be able to play
|
||||
with Modoboa, ie. your machine must be visible from your network.
|
||||
|
||||
The default network interface of the machine (``eth0``) is configured
|
||||
to use the DHCP protocol.
|
||||
|
||||
Connect to the machine
|
||||
======================
|
||||
|
||||
The following UNIX users are available if you want to connect to the system:
|
||||
|
||||
===== ======== ====================
|
||||
Login Password Description
|
||||
===== ======== ====================
|
||||
root demo the root user
|
||||
demo demo an unpriviliged user
|
||||
===== ======== ====================
|
||||
|
||||
To connect to Modoboa, first connect to the system and retrieve its
|
||||
current network address like this::
|
||||
|
||||
$ /sbin/ifconfig eth0
|
||||
|
||||
Once you know its address, open a web browser and go to this url::
|
||||
|
||||
http://<ip_address>/admin/
|
||||
|
||||
You should see the login page. Here are the users available by default:
|
||||
|
||||
================ ======== ============================================
|
||||
Login Password Capabitilies
|
||||
================ ======== ============================================
|
||||
admin password Default super administrator. Can do anything
|
||||
on the admin but can't access applications
|
||||
|
||||
admin@demo.local admin Administrator of the domain *demo.local*.
|
||||
Can administrater its domain and access to
|
||||
applications.
|
||||
|
||||
user@demo.local user Simple user. Can access to applications.
|
||||
================ ======== ============================================
|
||||
+1
-1
@@ -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.
|
||||
|
||||
+22
-2
@@ -1,4 +1,24 @@
|
||||
Rules
|
||||
#################
|
||||
How to contribute
|
||||
#################
|
||||
|
||||
Contributions are always welcome. If you want to submit a patch,
|
||||
please respect the following rules:
|
||||
|
||||
- Open a pull request on the appropriate repository
|
||||
- Respect `PEP8 <https://www.python.org/dev/peps/pep-0008/>`_
|
||||
- Document your patch and respect `PEP 257 <https://www.python.org/dev/peps/pep-0257/>`_
|
||||
- Add unit tests and make sure the global coverage does not decrease
|
||||
|
||||
If all those steps are validated, your contribution will generally be
|
||||
integrated.
|
||||
|
||||
Table of contents
|
||||
=================
|
||||
|
||||
.. include:: ../CONTRIBUTING.rst
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
contributing/getting_started
|
||||
contributing/plugin_api
|
||||
contributing/events
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
###############################
|
||||
Development recipes for Modoboa
|
||||
###############################
|
||||
###########
|
||||
Useful tips
|
||||
###########
|
||||
|
||||
You would like to work on Modoboa but you don't know where to start?
|
||||
You're at the right place! Browse this page to learn useful tips.
|
||||
@@ -51,8 +51,9 @@ You're ready to go!
|
||||
Manage static files
|
||||
===================
|
||||
|
||||
Modoboa uses `bower <http://bower.io/>`_ (thanks to `django-bower <https://github.com/nvbn/django-bower>`_)
|
||||
to manage its CSS and javascript dependencies.
|
||||
Modoboa uses `bower <http://bower.io/>`_ (thanks to `django-bower
|
||||
<https://github.com/nvbn/django-bower>`_) to manage its CSS and
|
||||
javascript dependencies.
|
||||
|
||||
Those dependencies are listed in a file called :file:`dev_settings.py`
|
||||
located inside the :file:`<path_to_local_copy>/modoboa/core`
|
||||
@@ -66,6 +67,42 @@ If you want to add a new dependency, just complete the
|
||||
It will download and store the required files into the
|
||||
:file:`<path_to_local_copy>/modoboa/bower_components` directory.
|
||||
|
||||
Test your modifications
|
||||
=======================
|
||||
|
||||
If you deployed a specific instance for your development needs, you
|
||||
can run the tests suite as follows:
|
||||
|
||||
.. sourcecode:: bash
|
||||
|
||||
> python manage.py test modoboa.core modoboa.lib modoboa.admin modoboa.limits modoboa.relaydomains
|
||||
|
||||
Otherwise, you can run the tests suite from the repository using `tox
|
||||
<https://tox.readthedocs.io>`_.
|
||||
|
||||
Start a basic Modoboa instance
|
||||
==============================
|
||||
|
||||
From the repository, run the following command to launch a simple
|
||||
instance with a few fixtures:
|
||||
|
||||
.. sourcecode:: bash
|
||||
|
||||
> tox -e serve
|
||||
|
||||
You can use admin/password to log in.
|
||||
|
||||
Build the documentation
|
||||
=======================
|
||||
|
||||
If you need to modify the documenation and want to see the result, you
|
||||
can build it as follows:
|
||||
|
||||
.. sourcecode:: bash
|
||||
|
||||
> tox -e doc
|
||||
> firefox .tox/doc/tmp/html/index.html
|
||||
|
||||
FAQ
|
||||
===
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
###################
|
||||
Adding a new plugin
|
||||
Create a new plugin
|
||||
###################
|
||||
|
||||
************
|
||||
@@ -14,19 +14,20 @@ implementation provides the following possibilities:
|
||||
* Register callback actions for specific events
|
||||
|
||||
Plugins are nothing more than Django applications with an extra piece
|
||||
of code that integrates them into Modoboa. The *modo_extension.py* file
|
||||
will contain a complete description of the plugin:
|
||||
of code that integrates them into Modoboa. The
|
||||
:file:`modo_extension.py` file will contain a complete description of
|
||||
the plugin:
|
||||
|
||||
* Admin and user parameters
|
||||
* Observed events
|
||||
* Custom menu entries
|
||||
|
||||
The communication between both applications is provided by
|
||||
:ref:`events`. Modoboa offers some kind of hooks to let plugin add custom
|
||||
actions.
|
||||
:ref:`events`. Modoboa offers some kind of hooks to let plugins add
|
||||
custom actions.
|
||||
|
||||
The following subsections describe plugin architecture and explain
|
||||
how you can create your own plugin.
|
||||
The following subsections describe the plugin architecture and explain
|
||||
how you can create your own.
|
||||
|
||||
*****************
|
||||
The required glue
|
||||
@@ -45,7 +46,6 @@ of the future extension::
|
||||
|
||||
|
||||
class MyExtension(ModoExtension):
|
||||
|
||||
"""My custom Modoboa extension."""
|
||||
|
||||
name = "myext"
|
||||
@@ -82,9 +82,9 @@ Parameters
|
||||
A plugin can declare its own parameters. There are two levels available:
|
||||
|
||||
* 'Administration' parameters : used to configure the plugin, editable
|
||||
inside the *Admin > Settings > Parameters* page,
|
||||
inside the *Admin > Settings > Parameters* page
|
||||
* 'User' parameters : per-user parameters (or preferences), editable
|
||||
inside the *Options > Preferences* page.
|
||||
inside the *Options > Preferences* page
|
||||
|
||||
Playing with parameters
|
||||
=======================
|
||||
@@ -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``.
|
||||
+64
-63
@@ -3,72 +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
|
||||
|
||||
getting_started/install
|
||||
getting_started/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
|
||||
additional/virtualmachine
|
||||
|
||||
*******************
|
||||
Contributing
|
||||
*******************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:maxdepth: 1
|
||||
|
||||
installation
|
||||
upgrade
|
||||
configuration
|
||||
rest_api
|
||||
contributing
|
||||
contributors
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
############
|
||||
Installation
|
||||
############
|
||||
|
||||
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 (modoboa,
|
||||
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:`manually <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 <mail server hostname>
|
||||
|
||||
Wait a few minutes and you're done \o/
|
||||
|
||||
.. _by_hand:
|
||||
|
||||
Manual installation
|
||||
===================
|
||||
|
||||
For those who need a manual installation or who just want to setup a
|
||||
specific part, here are the steps you must follow:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
manual_installation/modoboa
|
||||
manual_installation/webserver
|
||||
manual_installation/dovecot
|
||||
manual_installation/postfix
|
||||
|
||||
Extensions
|
||||
----------
|
||||
|
||||
Only few commands are needed to add a new extension to your setup.
|
||||
|
||||
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
|
||||
|
||||
Then, restart your web sever.
|
||||
@@ -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,71 +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 commands::
|
||||
|
||||
$ cd <modoboa_instance_path>
|
||||
$ python manage.py generate_postfix_maps --destdir <directory>
|
||||
|
||||
``<directory>`` is the directory where the files will be stored.
|
||||
|
||||
.. _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
|
||||
<driver>:/etc/postfix/sql-sender-login-mailboxes-extra.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.
|
||||
@@ -0,0 +1,142 @@
|
||||
#######
|
||||
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:
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,71 @@
|
||||
.. _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:
|
||||
|
||||
.. sourcecode:: bash
|
||||
|
||||
> cd <modoboa_instance_path>
|
||||
> python manage.py generate_postfix_maps --destdir <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
|
||||
<driver>:/etc/postfix/sql-sender-login-mailboxes-extra.cf
|
||||
|
||||
smtpd_sender_restrictions =
|
||||
reject_sender_login_mismatch
|
||||
|
||||
# Stuff after
|
||||
|
||||
Replace ``<driver>`` by the name of the database you use.
|
||||
|
||||
Restart Postfix.
|
||||
@@ -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.
|
||||
@@ -1,7 +0,0 @@
|
||||
.. _amavis_frontend:
|
||||
|
||||
####################
|
||||
Amavisd-new frontend
|
||||
####################
|
||||
|
||||
`Official documentation <http://modoboa-amavis.readthedocs.org>`_.
|
||||
@@ -1,7 +0,0 @@
|
||||
.. _postfix_ar:
|
||||
|
||||
###########################
|
||||
Postfix auto-reply messages
|
||||
###########################
|
||||
|
||||
`Official documentation <http://modoboa-postfix-autoreply.readthedocs.org>`_.
|
||||
@@ -1,5 +0,0 @@
|
||||
#################
|
||||
Radicale frontend
|
||||
#################
|
||||
|
||||
`Official documentation <http://modoboa-radicale.readthedocs.org>`_.
|
||||
@@ -1,5 +0,0 @@
|
||||
#############
|
||||
Sieve filters
|
||||
#############
|
||||
|
||||
`Official documentation <http://modoboa-sievefilters.readthedocs.org>`_.
|
||||
@@ -1,7 +0,0 @@
|
||||
.. _stats:
|
||||
|
||||
####################
|
||||
Graphical statistics
|
||||
####################
|
||||
|
||||
`Official documentation <http://modoboa-stats.readthedocs.org>`_.
|
||||
@@ -1,7 +0,0 @@
|
||||
.. _webmail:
|
||||
|
||||
#######
|
||||
Webmail
|
||||
#######
|
||||
|
||||
`Official documentation <http://modoboa-webmail.readthedocs.org>`_.
|
||||
@@ -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``.
|
||||
@@ -1,53 +1,88 @@
|
||||
##################################
|
||||
Upgrading an existing installation
|
||||
##################################
|
||||
#######
|
||||
Upgrade
|
||||
#######
|
||||
|
||||
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>
|
||||
Modoboa
|
||||
*******
|
||||
|
||||
.. 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.
|
||||
The new version you are going to install may need to modify your
|
||||
database. Before you start, make sure to backup everything!
|
||||
|
||||
If you prefer the manual way, check if
|
||||
:ref:`specific_upgrade_instructions` are required according to the
|
||||
version you're installing.
|
||||
Most of the time, upgrading your installation to a newer Modoboa
|
||||
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.
|
||||
|
||||
To finish, restart the web server process according to the environment
|
||||
you did choose. See :ref:`webservers` for more details.
|
||||
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 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 upgrade instructions
|
||||
*****************************
|
||||
Specific instructions
|
||||
*********************
|
||||
|
||||
1.6.0
|
||||
=====
|
||||
@@ -354,260 +389,3 @@ If you plan to use the Radicale extension:
|
||||
``<path to your site's dir>`` to ``<modoboa's root url>`` (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
|
||||
=======================================
|
||||
|
||||
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.
|
||||
@@ -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."""
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
factory-boy>=2.4
|
||||
testfixtures==4.7.0
|
||||
httmock==1.2.5
|
||||
tox
|
||||
|
||||
Reference in New Issue
Block a user