diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 99efbbdd1..5c18a6a0b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,19 +1 @@ -Contributions are always welcome but please try to follow those few rules: - -- Modoboa tries to respect the `PEP8 `_. - -- If you add some code, add some tests too. You can run the tests - suite locally by using `tox `_ - -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 diff --git a/doc/_static/api_access_form.png b/doc/_static/api_access_form.png new file mode 100644 index 000000000..fb1bf0257 Binary files /dev/null and b/doc/_static/api_access_form.png differ diff --git a/doc/_static/modoboa_logo.png b/doc/_static/modoboa_logo.png new file mode 100644 index 000000000..fe42c28ca Binary files /dev/null and b/doc/_static/modoboa_logo.png differ diff --git a/doc/additional/migrating.rst b/doc/additional/migrating.rst deleted file mode 100644 index 5aafe99a9..000000000 --- a/doc/additional/migrating.rst +++ /dev/null @@ -1,15 +0,0 @@ -################### -Tools for migration -################### - -****************************** -Migrate existing IMAP accounts -****************************** - -`OfflineIMAP extension `_. - -************ -PostfixAdmin -************ - -`Official repository `_. diff --git a/doc/additional/virtualmachine.rst b/doc/additional/virtualmachine.rst deleted file mode 100644 index 471c2c418..000000000 --- a/doc/additional/virtualmachine.rst +++ /dev/null @@ -1,74 +0,0 @@ -Using the virtual machine -************************* - -Introduction -============ - -A virtual machine with a ready-to-use Modoboa setup is available `here -`_. 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 -`_ 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 -`_ 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:///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. -================ ======== ============================================ diff --git a/doc/conf.py b/doc/conf.py index 44da751d4..c3b12f4a7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -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. diff --git a/doc/getting_started/configuration.rst b/doc/configuration.rst similarity index 100% rename from doc/getting_started/configuration.rst rename to doc/configuration.rst diff --git a/doc/contributing.rst b/doc/contributing.rst index f31145f8c..5ef78dfb8 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -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 `_ +- Document your patch and respect `PEP 257 `_ +- 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 diff --git a/doc/extending/events.rst b/doc/contributing/events.rst similarity index 100% rename from doc/extending/events.rst rename to doc/contributing/events.rst diff --git a/doc/extending/getting_started.rst b/doc/contributing/getting_started.rst similarity index 69% rename from doc/extending/getting_started.rst rename to doc/contributing/getting_started.rst index e36961b34..621e9a58f 100644 --- a/doc/extending/getting_started.rst +++ b/doc/contributing/getting_started.rst @@ -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 `_ (thanks to `django-bower `_) -to manage its CSS and javascript dependencies. +Modoboa uses `bower `_ (thanks to `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:`/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:`/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 +`_. + +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 === diff --git a/doc/extending/plugin_api.rst b/doc/contributing/plugin_api.rst similarity index 91% rename from doc/extending/plugin_api.rst rename to doc/contributing/plugin_api.rst index 984072927..5d2ff90e3 100644 --- a/doc/extending/plugin_api.rst +++ b/doc/contributing/plugin_api.rst @@ -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 ======================= diff --git a/doc/getting_started/install.rst b/doc/getting_started/install.rst deleted file mode 100644 index 0446d7583..000000000 --- a/doc/getting_started/install.rst +++ /dev/null @@ -1,200 +0,0 @@ -.. _installation: - -############ -Installation -############ - -***************** -For the lazy ones -***************** - -If you are in a hurry, you will love the `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 - -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+ `_ -* `Django version 1.7+ `_ -* `lxml python module `_ -* `pycrypto python module `_ -* `rrdtool python binding `_ -* `sievelib python module `_ -* `chardet python module `_ -* `argparse python module `_ -* `reversion python module `_ - -.. _get_modoboa: - -*********** -Get Modoboa -*********** - -You can choose between two options: - -* Use the Python package available on the `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-.tar.gz - $ cd modoboa- - $ 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 `_ 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 `_ for `MySQL `_ -* `psycopg2 `_ for `PostgreSQL `_ - -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 - `_ extension, use the - ``amavis:`` prefix. An example two connections: ``--dburl - default: amavis:``. - - 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 = '//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``. diff --git a/doc/index.rst b/doc/index.rst index fa9ecd85a..baf128dbd 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -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 +`_ and `Dovecot `_. + +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 | +|`_ |`_| | +| | | | +| | | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-dmarc |A set of tools to use |https://github.com/modoboa-dmarc | +|`_ |`DMARC | | +| |`_ | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-imap-migration |Migrate mailboxes from an|https://github.com/modoboa-imap-migration | +|`_ |existing server using | | +| |IMAP (and offlineimap) | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-pdfcredentials |Generate PDF documents |https://github.com/modoboa-pdfcredentials | +|`_ |containing account | | +| |credentials | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-pfxadmin-migrate |A tool to migrate from |https://github.com/modoboa/modoboa-pfxadmin-migrate | +|`_ |Postfixadmin | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-postfix-autoreply |Away message editor |https://modoboa-postfix-autoreply.readthedocs.io | +|`_|(postfix compatible) | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-radicale |A frontend for `Radicale |https://modoboa-radicale.readthedocs.io | +|`_ |`_ | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-sievefilters |A Sieve filters (rules) |https://modoboa-sievefilters.readthedocs.io | +|`_ |editor | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-stats |Graphical statistics |https://modoboa-stats.readthedocs.io | +|`_ |(message traffic and | | +| |more) | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ +|`modoboa-webmail |A simple webmail |https://modoboa-webmail.readthedocs.io | +|`_ | | | ++------------------------------------------------+-------------------------+------------------------------------------------------+ + +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 diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 000000000..4c2d26836 --- /dev/null +++ b/doc/installation.rst @@ -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 +`_! 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 `. + +To use it, just run the following commands in your terminal: + +.. sourcecode:: bash + + > git clone https://github.com/modoboa/modoboa-installer + > cd modoboa-installer + > sudo ./run.py + +Wait a few minutes and you're done \o/ + +.. _by_hand: + +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 + > source /bin/activate + +Then, run the following commands: + +.. sourcecode:: bash + + > pip install == + > cd + > python manage.py migrate + > python manage.py collectstatic + +Then, restart your web sever. diff --git a/doc/integration/imap_and_smtp.rst b/doc/manual_installation/dovecot.rst similarity index 83% rename from doc/integration/imap_and_smtp.rst rename to doc/manual_installation/dovecot.rst index 60bfd23a4..60fdaa319 100644 --- a/doc/integration/imap_and_smtp.rst +++ b/doc/manual_installation/dovecot.rst @@ -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 -`_ 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 - $ python manage.py generate_postfix_maps --destdir - -```` 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 = :/etc/postfix/sql-domains.cf - virtual_alias_domains = :/etc/postfix/sql-domain-aliases.cf - virtual_alias_maps = :/etc/postfix/sql-aliases.cf - - relay_domains = :/etc/postfix/sql-relaydomains.cf - transport_maps = - :/etc/postfix/sql-spliteddomains-transport.cf - :/etc/postfix/sql-relaydomains-transport.cf - - smtpd_recipient_restrictions = - # ... - check_recipient_access - :/etc/postfix/sql-maintain.cf - :/etc/postfix/sql-relay-recipient-verification.cf - permit_mynetworks - reject_unauth_destination - reject_unverified_recipient - # ... - - smtpd_sender_login_maps = - :/etc/postfix/sql-sender-login-mailboxes.cf - :/etc/postfix/sql-sender-login-aliases.cf - :/etc/postfix/sql-sender-login-mailboxes-extra.cf - - smtpd_sender_restrictions = - reject_sender_login_mismatch - - # Stuff after - -Replace ```` by the name of the database you use. - -Restart Postfix. +Now, you can go to the :ref:`postfix` section to finish the installation. diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst new file mode 100644 index 000000000..865492e00 --- /dev/null +++ b/doc/manual_installation/modoboa.rst @@ -0,0 +1,142 @@ +####### +Modoboa +####### + +This section describes the installation of the web interface (a +`Django `_ project). + +Prepare the system +------------------ + +First of all, we recommand the following context: + +* Use a dedicated system user +* Use a `virtualenv `_ to + install the application because it will isolate it (and its + dependencies) from the rest of your system + +The following example illustrates how to realize this (Debian like system): + +.. sourcecode:: bash + + > sudo apt-get install python-virtualenv python-pip + > sudo useradd modoboa + > sudo -i modoboa + > virtualenv env + (env)> source env/bin/activate + (env)> pip install -U pip + +FIXME: dépendances système pour compilation + +Then, install Modoboa: + +.. sourcecode:: bash + + (env)> pip install modoboa + +.. _database: + +Database +-------- + +.. warning:: + + This documentation does not cover the installation of a database + server but only the setup of a functional database that Modoboa + will use. + +Thanks to Django, Modoboa is compatible with the following databases: + +* PostgreSQL +* MySQL / MariaDB +* SQLite + +Since the last one does not require particular actions, only the first +two ones are described. + +PostgreSQL +********** + +Install the corresponding Python binding: + +.. sourcecode:: bash + + (env)> pip install psycopg2 + +Then, create a user and a database: + +.. sourcecode:: bash + + > sudo -i postgres + > + +MySQL / MariaDB +*************** + +Install the corresponding Python binding: + +.. sourcecode:: bash + + (env)> pip install MySQL-Python + +Then, create a user and a database: + +.. sourcecode:: bash + + > mysqladmin -u root -p create modoboa + +Deploy an instance +------------------ + +``modoboa-admin.py``, a command line tool, lets you deploy a +*ready-to-use* Modoboa site using only one instruction:: + + (env)> modoboa-admin.py deploy instance --collectstatic \ + --domain --dburl default:database-url + +.. note:: + + You can install additional extensions during the deploy process. To + do so, use the ``--extensions`` option which accepts a list of + names as argument (``--extensions ext1 ext2 ...``). If you want to + install all extensions, just use the ``all`` keyword like this + ``--extensions all``. + + If you choose to install extensions one at a time, you will have to + add their names in settings.py to ``MODOBOA_APPS``. Also ensure that + you have the line ``from modoboa_amavis.settings import *`` at the + end of this file. + + The list of available extensions can be found on the :doc:`index + page <../index>`. Instructions to install them are available on + each extensions page. + +.. note:: + + You can specify more than one database connection using the + ``--dburl`` option. Multiple connections are differentiated by a + prefix. + + The primary connection must use the ``default:`` prefix (as shown + in the example above). For the `amavis + `_ extension, use the + ``amavis:`` prefix. For example: ``--dburl + default: amavis:``. + + A database url should meet the following syntax + ``://[user:pass@][host:port]/dbname`` **OR** + ``sqlite:////full/path/to/your/database/file.sqlite``. + +The command will ask you a few questions, answer them and you're +done. + +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. diff --git a/doc/manual_installation/postfix.rst b/doc/manual_installation/postfix.rst new file mode 100644 index 000000000..18df715a2 --- /dev/null +++ b/doc/manual_installation/postfix.rst @@ -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 +`_ 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 + > python manage.py generate_postfix_maps --destdir + +```` 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 = :/etc/postfix/sql-domains.cf + virtual_alias_domains = :/etc/postfix/sql-domain-aliases.cf + virtual_alias_maps = :/etc/postfix/sql-aliases.cf + + relay_domains = :/etc/postfix/sql-relaydomains.cf + transport_maps = + :/etc/postfix/sql-spliteddomains-transport.cf + :/etc/postfix/sql-relaydomains-transport.cf + + smtpd_recipient_restrictions = + # ... + check_recipient_access + :/etc/postfix/sql-maintain.cf + :/etc/postfix/sql-relay-recipient-verification.cf + permit_mynetworks + reject_unauth_destination + reject_unverified_recipient + # ... + + smtpd_sender_login_maps = + :/etc/postfix/sql-sender-login-mailboxes.cf + :/etc/postfix/sql-sender-login-aliases.cf + :/etc/postfix/sql-sender-login-mailboxes-extra.cf + + smtpd_sender_restrictions = + reject_sender_login_mismatch + + # Stuff after + +Replace ```` by the name of the database you use. + +Restart Postfix. diff --git a/doc/integration/web_servers.rst b/doc/manual_installation/webserver.rst similarity index 88% rename from doc/integration/web_servers.rst rename to doc/manual_installation/webserver.rst index 851738c5d..e4f5164d0 100644 --- a/doc/integration/web_servers.rst +++ b/doc/manual_installation/webserver.rst @@ -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:: ServerName - DocumentRoot + DocumentRoot - Alias /media/ /media/ - /media> + Alias /media/ /media/ + /media> Order deny,allow Allow from all - Alias /sitestatic/ /sitestatic/ - /sitestatic> + Alias /sitestatic/ /sitestatic/ + /sitestatic> Order deny,allow Allow from all - WSGIScriptAlias / /wsgi.py + WSGIScriptAlias / //wsgi.py + 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=:/lib/python2.7/site-packages + WSGIDaemonProcess example.com python-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 `_ using a WSGI application server. Choose the one you prefer between `Green Unicorn `_ or @@ -86,7 +76,7 @@ In both cases, you'll need to download and `install nginx `_. Green Unicorn -============= ++++++++++++++ Firstly, `Download and install gunicorn `_. Then, use the following sample @@ -120,7 +110,7 @@ following configuration:: keepalive_timeout 70; server_name ; - root ; + root ; access_log /var/log/nginx/.access.log; error_log /var/log/nginx/.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: ```` 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. diff --git a/doc/plugins/amavis.rst b/doc/plugins/amavis.rst deleted file mode 100644 index 268448917..000000000 --- a/doc/plugins/amavis.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _amavis_frontend: - -#################### -Amavisd-new frontend -#################### - -`Official documentation `_. diff --git a/doc/plugins/postfix_autoreply.rst b/doc/plugins/postfix_autoreply.rst deleted file mode 100644 index e1683a6b6..000000000 --- a/doc/plugins/postfix_autoreply.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _postfix_ar: - -########################### -Postfix auto-reply messages -########################### - -`Official documentation `_. diff --git a/doc/plugins/radicale.rst b/doc/plugins/radicale.rst deleted file mode 100644 index 456529d41..000000000 --- a/doc/plugins/radicale.rst +++ /dev/null @@ -1,5 +0,0 @@ -################# -Radicale frontend -################# - -`Official documentation `_. diff --git a/doc/plugins/sievefilters.rst b/doc/plugins/sievefilters.rst deleted file mode 100644 index 0d714afc9..000000000 --- a/doc/plugins/sievefilters.rst +++ /dev/null @@ -1,5 +0,0 @@ -############# -Sieve filters -############# - -`Official documentation `_. diff --git a/doc/plugins/statistics.rst b/doc/plugins/statistics.rst deleted file mode 100644 index 50fd452b0..000000000 --- a/doc/plugins/statistics.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _stats: - -#################### -Graphical statistics -#################### - -`Official documentation `_. diff --git a/doc/plugins/webmail.rst b/doc/plugins/webmail.rst deleted file mode 100644 index b9df5e984..000000000 --- a/doc/plugins/webmail.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _webmail: - -####### -Webmail -####### - -`Official documentation `_. diff --git a/doc/rest_api.rst b/doc/rest_api.rst new file mode 100644 index 000000000..70178848b --- /dev/null +++ b/doc/rest_api.rst @@ -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:///api/v1/* +* Documentation: *http:///docs/api/* + +An `example `_ 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 + +and the content type of those requests must be ``application/json``. diff --git a/doc/getting_started/upgrade.rst b/doc/upgrade.rst similarity index 52% rename from doc/getting_started/upgrade.rst rename to doc/upgrade.rst index 8b79350d1..2dd849b87 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/upgrade.rst @@ -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== - -Replace ```` 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 +******* .. 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 + > source /bin/activate + +Then, run the following commands: + +.. sourcecode:: bash + + > pip install modoboa== + > cd + > python manage.py migrate + > python manage.py collectstatic + +Once done, check if the version you are installing requires +:ref:`specific_upgrade_instructions`. + +Finally, restart your web server. + +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 + +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 + > source /bin/activate + +Then, run the following commands: + +.. sourcecode:: bash + + > pip install == + > cd + > 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: ```` to ```` (it's probably the parent directory). You have to adapt your web server configuration to reflect this change. - -1.1.7: manual learning for SpamAssassin -======================================= - -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 ` and -:ref:`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 `. Look at the -``smtpd_recipient_restrictions`` setting. - -Run ``modoboa-admin.py postfix_maps --dbtype -`` 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 = [ - '', - ] - -#. 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 `` 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 ` - -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. diff --git a/modoboa/core/forms.py b/modoboa/core/forms.py index 816dc5878..45bdb5f55 100644 --- a/modoboa/core/forms.py +++ b/modoboa/core/forms.py @@ -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.""" diff --git a/test-requirements.txt b/test-requirements.txt index a1b4ef1c5..554f0a065 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -1,3 +1,4 @@ factory-boy>=2.4 testfixtures==4.7.0 httmock==1.2.5 +tox