diff --git a/doc/conf.py b/doc/conf.py index 9ec5b9658..af57a6f7b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -48,9 +48,9 @@ copyright = u'2012, Antoine Nguyen' # built documents. # # The short X.Y version. -version = '0.9.2' +version = '0.9.3' # The full version, including alpha/beta/rc tags. -release = '0.9.2' +release = '0.9.3' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/doc/getting_started/install.rst b/doc/getting_started/install.rst index e2ac80e57..dce643e24 100644 --- a/doc/getting_started/install.rst +++ b/doc/getting_started/install.rst @@ -15,6 +15,8 @@ Requirements * `pycrypto python module `_ * `rrdtool python binding `_ * `sievelib python module `_ +* `chardet python module `_ +* `argparse python module `_ .. _get_modoboa: @@ -44,7 +46,7 @@ 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 includes a ready-to-use +Fortunately, all major distributions include a ready-to-use package. On Debian/Ubuntu:: $ apt-get install python-rrdtool @@ -70,12 +72,33 @@ sure your database is using UTF8 as a default charset. Deployment ********** +Automatic +========= + +`modoboa-admin.py`, a command line tool, let you deploy a +*ready-to-use* Modoboa site using only one instruction:: + + $ modoboa-admin.py deploy modoboa_example --syncdb --collectstatic [--with-amavis] + +Just answer the few questions and you're done. You can now go to the +:ref:`first_use` section. + +.. note:: + + The `--with-amavis` option must be set only if you intend to use + the :ref:`amavis_frontend`. + +Manual +====== + As Modoboa is a set of Django applications, you need to create a new project. Just run the following commands:: $ cd /var/www $ django-admin.py startproject modoboa_example $ cd modoboa_example + $ rm settings.py + $ rm urls.py $ wget http://modoboa.org/resources/settings.py $ wget http://modoboa.org/resources/urls.py $ mkdir media @@ -92,9 +115,15 @@ Finally, run the following commands:: $ python manage.py collectstatic $ python manage.py syncdb --migrate --noinput + $ python manage.py loaddata initial_users.json -At the end of this command, a default super administrator is -available: +.. _first_use: + +********* +First use +********* + +Your installation should now have a default super administrator: * Username: ``admin`` * Password: ``password`` @@ -107,7 +136,7 @@ server:: $ python manage.py runserver -You should be able to access your site at http://locahost:8000/. +You should be able to access Modoboa at http://locahost:8000/. For a production environnement, we recommend using a stable webserver like :ref:`apache2` or :ref:`nginx-label`. diff --git a/doc/getting_started/plugins.rst b/doc/getting_started/plugins.rst index dc68888d7..bb00c1310 100644 --- a/doc/getting_started/plugins.rst +++ b/doc/getting_started/plugins.rst @@ -261,25 +261,15 @@ configuration files as follow: ```` is the path of your Modoboa instance. -Then, create new map files with the following content: +Then, create the requested map files:: -``/etc/postfix/maps/sql-transport.cf``:: + $ modoboa-admin.py postfix_maps mapfiles --categories autoreply - user = - password = - dbname = - hosts = 127.0.0.1 - query = SELECT method FROM postfix_autoreply_transport WHERE domain='%s' - -``/etc/postfix/maps/sql-autoreplies.cf``:: - - user = - password = - dbname = - hosts = 127.0.0.1 - query = SELECT full_address, autoreply_address FROM postfix_autoreply_alias WHERE full_address='%s' +`mapfiles` is the directory where the files will be stored. Answer the +few questions and you're done. .. note:: + Auto-reply messages are just sent one time per sender for a pre-defined time period. By default, this period is equal to 1 day (86400s), you can adjust this value by modifying the ``AUTOREPLY_TIMEOUT`` diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst index bd49c6b6f..74a5b1422 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/getting_started/upgrade.rst @@ -29,8 +29,9 @@ Then, follow the common procedure:: $ python manage.py syncdb --migrate $ python manage.py collectstatic -Finally, refer to this page to see if the version you're installing -requires specific operations. +Finally, refer to this page to check if the version you're installing +requires specific operations. If the version you're looking for is not +present, it means nothing special is required. 0.9.1: standard django application and more =========================================== diff --git a/doc/integration/smtp_servers.rst b/doc/integration/smtp_servers.rst index dea3d1908..8cecdaa05 100644 --- a/doc/integration/smtp_servers.rst +++ b/doc/integration/smtp_servers.rst @@ -12,9 +12,31 @@ 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. + +Automatic generation +-------------------- + +To automaticaly generate the requested map files and store them in a +directory, run the following command:: + + $ modoboa-admin.py postfix_maps --dbtype mapfiles + +`mapfiles` is the directory where the files will be stored. Answer the +few questions and you're done. + +.. _manual_map_files: + +Manual generation +----------------- + .. note:: - The SQL queries presented below are working well with MySQL + The SQL queries presented below are working only with MySQL only. To make them work with PostgreSQL, just replace (when needed) the `concat` function call by the standard concatenation operator (ie. `||`). @@ -62,7 +84,26 @@ Define the following map files on your server (it should work with hosts = 127.0.0.1 query = SELECT DISTINCT concat(mb.address, '@', dom.name) FROM admin_alias al INNER JOIN admin_domain dom ON dom.id=al.domain_id INNER JOIN admin_domainalias domal ON domal.target_id=dom.id INNER JOIN (admin_alias_mboxes almb, admin_mailbox mb) ON (almb.alias_id=al.id AND almb.mailbox_id=mb.id) WHERE domal.name='%d' AND domal.enabled=1 AND (al.address='%u' OR mb.address='%u') -Then, use the following configuration in the */etc/postfix/main.cf* file +``/etc/postfix/sql-email2email.cf``:: + + user = + password = + dbname = + hosts = 127.0.0.1 + query = SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN auth_user user ON mb.user_id=user.id WHERE dom.name='%d' AND dom.enabled=1 AND mb.address='%u' AND user.is_active=1 + +``/etc/postfix/sql-catchall-aliases.cf``:: + + user = + password = + dbname = + hosts = 127.0.0.1 + query = (SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.id IN (SELECT al_mb.mailbox_id FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id INNER JOIN admin_alias_mboxes al_mb ON al.id=al_mb.alias_id WHERE al.enabled=1 AND al.address='*' AND dom.name='%d' AND dom.enabled=1)) UNION (SELECT al.extmboxes FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id WHERE al.enabled='1' AND al.extmboxes<>'' AND al.address='*' AND dom.name='%d' AND dom.enabled=1) + +Configuration +============= + +Use the following configuration in the */etc/postfix/main.cf* file (this is just one possible configuration):: # Stuff before @@ -78,7 +119,10 @@ Then, use the following configuration in the */etc/postfix/main.cf* file virtual_alias_domains = mysql:/etc/postfix/sql-domain-aliases.cf virtual_mailbox_maps = mysql:/etc/postfix/sql-mailboxes.cf virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf, - mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf + mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf, + mysql:/etc/postfix/sql-email2email.cf, + mysql:/etc/postfix/sql-catchall-aliases.cf + # Stuff after .. note:: @@ -86,47 +130,12 @@ Then, use the following configuration in the */etc/postfix/main.cf* file which format to use by modifying the MAILBOX_TYPE parameter available in the admin panel. -Optional : 'catchall' aliases -============================= - -Modoboa supports 'catchall' aliases creation. In the case you would -like to use this feature, you'll need to add specific queries to -*postfix* configuration. - -First, create the following new maps (*MySQL* users): - -``/etc/postfix/sql-email2email.cf``:: - - user = - password = - dbname = - hosts = 127.0.0.1e - query = SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id INNER JOIN auth_user user ON mb.user_id=user.id WHERE dom.name='%d' AND dom.enabled=1 AND mb.address='%u' AND user.is_active=1 - -``/etc/postfix/sql-catchall-aliases.cf``:: - - user = - password = - dbname = - hosts = 127.0.0.1 - query = (SELECT concat(mb.address, '@', dom.name) FROM admin_mailbox mb INNER JOIN admin_domain dom ON mb.domain_id=dom.id WHERE mb.id IN (SELECT al_mb.mailbox_id FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id INNER JOIN admin_alias_mboxes al_mb ON al.id=al_mb.alias_id WHERE al.enabled=1 AND al.address='*' AND dom.name='%d' AND dom.enabled=1)) UNION (SELECT al.extmboxes FROM admin_alias al INNER JOIN admin_domain dom ON al.domain_id=dom.id WHERE al.enabled='1' AND al.extmboxes<>'' AND al.address='*' AND dom.name='%d' AND dom.enabled=1) - -Once done, edit the *main.cf* configuration file and add the new maps -to the ``virtual_alias_maps`` parameter like this:: - - virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf, - mysql:/etc/postfix/sql-domain-aliases-mailboxes.cf, - mysql:/etc/postfix/sql-email2email.cf, # new - mysql:/etc/postfix/sql-catchall-aliases.cf # new - -Reload *postfix*. - .. _dovecot_lda: -Optional: using Dovecot's LDA -============================= +Recommended: using Dovecot's LDA +================================ -If you are using *Dovecot* in your environnement, I recommend to use +If you are using *Dovecot* in your environnement, we recommend to use its LDA. Doing so, you'll will be able to use extra functionalities such as sieve filters and more. @@ -142,7 +151,7 @@ definition at the end:: dovecot unix - n n - - pipe flags=DRhu user=vmail:vmail argv=/usr/lib/dovecot/deliver -f ${sender} -d ${recipient} -If you have followed the :ref:`postfix` section to install your +If you have followed the :ref:`manual_map_files` section to install your environnement, you need to modify the SQL query corresponding to the ``virtual_mailbox_maps`` parameter. Edit the */etc/postfix/maps/sql-mailboxes.cf* and modify the ``query`` diff --git a/requirements.txt b/requirements.txt index 1afe6047f..b49f60429 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,4 @@ lxml pycrypto sievelib chardet +argparse