source: INSTALL @ 160:afaf7e4f14e6

Installation
============

Requirements
------------

- Python version 2.6+
- Django version 1.0+ (http://docs.djangoproject.com/en/dev/intro/install/#intro-install)

How to install
--------------

Download Mailng's tarball and extract it::

  tar xzf mailng-<version>.tar.gz
  mv mailng-<version> mailng

Settings file

  Enter the mailng directory, create a settings.py file (you can use
  settings-sample.py as a model).
  Specify database relative informations.
  You must choose between mysql and postgresql, other types are not supported by
  major email projects like postfix or dovecot.
  Create a database with the name you specified in settings.py.
  you will probably need python database module backend like MySQLdb.
  Modify TEMPLATE_DIRS.

Initialise the database by running the following command::

  python manage.py syncdb

Create the super admin account (just follow the procedure).

Run the initialisation script. It will insert needed data into the database :

  export PYTHONPATH=$PWD/..
  DJANGO_SETTINGS_MODULE=mailng.settings ./scripts/populate.py

How to upgrade
--------------
0.7 -> 0.8 : SQL migration needed.

south is needed to handle migrations. You will find instructions on
how to install south here:
http://south.aeracode.org/docs/installation.html.

NB: Before doing this migration, I recommend that you make a copy of your
existing database.

When this is done, add 'mailng.lib' and 'south' to your
INSTALLED_APPS. Then, run the following commands:

  # python manage.py syncdb
  # python manage.py convert_to_south
  # python manage.py migrate --all 0001 --fake
  # python manage.py migrate --all 0002

0.6 -> 0.7 : no SQL modifications.
0.5 -> 0.6 : no SQL modifications.

If no modifications have been made to the core SQL schema, juste
decompress the new tarball at the same location than your current
installation.

Time zone and language
----------------------

MailNG is available in english, french and german. You can choose
which language to use by modifying the LANGUAGE_CODE variable inside
settings.py::

  LANGUAGE_CODE = 'en-US' # English
  # or
  LANGUAGE_CODE = 'fr-FR' # French
  # or
  LANGUAGE_CODE = 'de-DE' # German

You can also specify your time zone by modifying the TIME_ZONE
variable. For example::

  TIME_ZONE = 'Europe/Paris'

Host configuration
------------------

Before testing Mailng, you must create a group and a user that will be
used to store mails on the host filesystem. There is only one
group/user needed because we are in a virtual hosting configuration
(ie. users with non-UNIX accounts).

For example, create a vmail group::

  groupadd vmail

Then create a vmail user::

  useradd -g vmail -d /var/vmail -m vmail

At last, the system user used to run mailng will need permissions to
manipulate directories in vmail's homedir. To do that, edit your /etc/sudoers
file and add the following inside::

  www-data ALL=(vmail) NOPASSWD: ALL

Testing installation
--------------------

As a typical Django application, Mailng can be tested using a simple web 
server. Just run this command to start it::

  python manage.py runserver

You will be able to play with mailng by looking at 
http://<youraddress>:8000/mailng/admin/.

Tips to link Mailng with postfix
--------------------------------

First, define following maps on your server (this should work with
Postfix versions >= 2.2)::

# /etc/postfix/sql-domains.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT name FROM admin_domain WHERE name='%s' AND enabled='1'

# /etc/postfix/sql-mailboxes.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT path FROM admin_mailbox WHERE full_address = '%s'

# /etc/postfix/sql-aliases.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT t3.full_address FROM admin_alias AS t1, admin_alias_mboxes AS t2, admin_mailbox AS t3 WHERE t1.full_address='%s' AND t1.id=t2.alias_id AND t2.mailbox_id=t3.id AND t1.enabled='1'

Then, use the following configuration in your /etc/postfix/main.cf file
(this is one possible configuration)::

  # Stuff before
  mailbox_transport = virtual
  home_mailbox = .maildir/ 
  maildrop_destination_recipient_limit = 1
  virtual_minimum_uid = <vmail user id> 
  virtual_gid_maps = static:<vmail group id>
  virtual_uid_maps = static:<vmail user id>
  virtual_mailbox_base = /var/vmail

  relay_domains = 
  virtual_mailbox_domains = mysql:/etc/postfix/sql-domains.cf
  virtual_mailbox_maps = mysql:/etc/postfix/sql-mailboxes.cf
  virtual_alias_maps = mysql:/etc/postfix/sql-aliases.cf
  # Stuff after

NB: Mailng supports both maildir and mbox formats. You can specify
which format to use by modifying the MAILBOX_TYPE variable located
inside 'settings.py'.

Tips to activate auto-reply messages in Postifx
-----------------------------------------------

Since version 0.6, mail users can define an auto-reply message with MailNG.

To activate the extension, edit your settings.py and add the following
line inside the INSTALLED_APPS variable::

  'mailng.extensions.postfix_autoreply',

Then run the following commands to update MailNG SQL schema and content::

  # python manage.py syncdb
  # export PYTHONPATH=$PWD/..
  # DJANGO_SETTINGS_MODULE=mailng.settings ./scripts/upgrade_autoreply.py

To make Postfix understand this feature, you need to update your configuration
files as follow::

 # /etc/postfix/main.cf
  transport_maps = mysql:/etc/postfix/maps/sql-transport.cf
  virtual_alias_maps = mysql:/etc/postfix/maps/sql-aliases.cf
          mysql:/etc/postfix/maps/sql-autoreplies.cf

 # /etc/postfix/master.cf
  autoreply unix        -       n       n       -       -       pipe
            flags= user=nobody argv=<path_to_mailng>/scripts/autoreply $sender $mailbox

Then, create new map files with the following content::

 # /etc/postfix/maps/sql-transport.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT method FROM postfix_autoreply_transport WHERE domain='%s'

 # /etc/postfix/maps/sql-autoreplies.cf
  user = <user>
  password = <password>
  dbname = <database>
  hosts = 127.0.0.1
  query = SELECT full_address, autoreply_address FROM postfix_autoreply_alias WHERE full_address='%s'

Finally, edit the shell script 'autoreply' located inside the
'scripts' directory and change the value of BASEDIR. (just put absolute path
of the directory where mailng is installed)

NB: 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
variable located inside 'settings.py'.

NB: Be sure that both 'autoreply' and 'autoreply.py' scripts (located
inside the 'scripts' directory) have good permissions (ie. 0755).

Tips to link Mailng with dovecot
--------------------------------

If you are using 'maildir' format to store mailboxes, add the
following line inside your main Dovecot config file
(/etc/dovecot/dovecot.conf)::

  mail_location = maildir:<path_to_mailboxes>/%d/%n/.maildir

If you are using 'mbox' format, put the following::
  
  mail_location = mbox:<path_to_mailboxes>/%d/%n/:INBOX=<path_to_mailboxes>/%d/%n/Inbox

To make the authentication work, edit 'dovecot.conf' and add the
following inside::

  auth default {
    # ... stuff before

    passdb sql {
      # Path for SQL configuration file, see /etc/dovecot/dovecot-sql.conf for
      #  example
      args = /etc/dovecot/dovecot-sql.conf
    }
    
    userdb sql {
      # Path for SQL configuration file
      args = /etc/dovecot/dovecot-sql.conf
    }

    # ... stuff after
  }

Be sure to activate only one backend (per type) inside your configuration
(comment other ones).

Then, edit your /etc/dovecot/dovecot-sql.conf and modify following lines::

  driver = mysql
  connect = host=<mysqld socket> dbname=<database> user=<user> password=<password>
  default_pass_scheme = PLAIN-MD5
  password_query = SELECT full_address AS user, password FROM admin_mailbox WHERE full_address = '%u'
  user_query = SELECT path AS home, uid, gid FROM admin_mailbox WHERE full_address = '%u'

Enable quotas with Dovecot
--------------------------

Put the following lines inside your dovecot.conf file::

    protocol imap {
      mail_plugins = quota quota_imap
    }

Before continuing, you need to know which quota backend must be user
(function of mailboxes format):: 
 * 'mbox' : backend=dirsize,
 * 'maildir' : backend=maildir.

If you use version prior to 1.1, add also the following configuration::

  plugin {
    # 10 MB default quota limit
    quota = <backend>:storage=10240
  }

Then modify the above user_query inside dovecot-sql.conf file like
that to activate per user quotas::

  user_query = SELECT path AS home, uid, gid, concat('<backend>:storage=', quota / 1024) AS quota FROM admin_mailbox WHERE full_address = '%u'

For version >= 1.1, put the following configuration inside dovecot.conf file::

  plugin {
    # Default 10M storage limit with an extra 5M limit when saving to Trash.
    quota = <backend>:User quota
    quota_rule = *:storage=10M
    quota_rule2 = Trash:storage=5M
  }

Then modify the above user_query inside dovecot-sql.conf to activate
user quotas::

  user_query = SELECT path AS home, uid, gid, concat('*:storage=', quota, 'M') AS quota_rule FROM admin_mailbox WHERE full_address = '%u'

Tips to serve Mailng behind Apache2
------------------------------------

First, be sure to have apache2 and mod_python installed on your
server.

Create a new virtualhost in your Apache configuration and put the
following inside::

  <VirtualHost *:80>
    <Location "/">
      SetHandler mod_python
      PythonHandler django.core.handlers.modpython
      PythonPath "['<path to directory that contains mailng dir>'] + sys.path"
      SetEnv DJANGO_SETTINGS_MODULE mailng.settings
    </Location>
    Alias "/static" "<path to mailng dir>/static"
    <Location "/static/">
      SetHandler None
    </Location>
  </VirtualHost>

This is one possible configuration. Note that you will certainly need more
configuration in order to launch Apache.

Using the amavisd-new quarantine plugin
---------------------------------------

This plugin allows you and your users to handle amavisd-new SQL
quarantine. You can consult messages and/or release or delete them.

If you plan to use it, first make sure to have those requirements
installed on your server::

- mysqldb python module (http://mysql-python.sourceforge.net/)
- lxml python module (http://codespeak.net/lxml/)

To activate the extension, edit your settings.py and add the following
line inside the INSTALLED_APPS variable::

  'mailng.extensions.amavis_quarantine',

Just run the following command to update MailNG SQL schema::
  
  # python manage.py syncdb

Then, you need to specify where is the database that contains the
quarantine. Inside settings.py, add a new connection to the
DB_CONNECTIONS variable like this::

  DB_CONNECTIONS = {
    "amavis_quarantine" : {"driver"   : "mysql",
                            "host"     : "<your_host>",
                            "dbname"   : "<amavis_dbname>",
                            "login"    : "<user>",
                            "password" : "<password>"}
  }
     

Replace values between <> with yours.

Finally, create a symbolic link to the templates directory inside the
main templates directory::

  # ln -s <mailng_dir>/extensions/amavis_quarantine/templates \
        templates/amavis_quarantine

When viewing messages, you can choose to display links (addresses,
images). In order to display images correctly, you need to create a
tmp directory under static/ for storing them. For example::

  # mkdir <mailng_dir>/static/tmp

To be able to release messages, first take a look at this page::

http://www.ijs.si/software/amavisd/amavisd-new-docs.html#quar-release

It shows how to configure amavisd-new to listen somewhere for the
AM.PDP protocol. This protocol is used to send release requests.

Below is an example of a working configuration::

  $interface_policy{'SOCK'} = 'AM.PDP-SOCK';
  $interface_policy{'9998'} = 'AM.PDP-INET';

  $policy_bank{'AM.PDP-SOCK'} = {
    protocol => 'AM.PDP',
    auth_required_release => 0,
  };
  $policy_bank{'AM.PDP-INET'} = {
    protocol => 'AM.PDP',
    inet_acl => [qw( 127.0.0.1 [::1] )],
  };

Don't forget to update the inet_acl list if you plan to release from
the network.

Once amavisd-new is configured, just tell MailNG where it can find the
"release server" by modifying following variables inside settings.py::

  # "unix" or "inet"
  AM_PDP_MODE = "inet"

  # "unix" mode only
  AM_PDP_SOCKET = "/var/amavis/amavisd.sock"

  # "inet" mode only
  AM_PDP_HOST = "127.0.0.1"
  AM_PDP_PORT = 9998

Last point, MailNG provides a simple script that periodically purge
the amavisd-new quarantine database. If you plan to use it, you can
add the following line inside root's crontab::

  0 0 * * * PYTHONPATH=<mailng_dir/..> \
    DJANGO_SETTINGS_MODULE=mailng.settings \
    <mailng_dir>/extensions/amavis_quarantine/cleanup.py

Replace mailng_dir with the installation path of MailNG.

By default, messages older than 14 days are automatically purged. You
can modify this value by changing the variable MAX_MESSAGES_AGE inside
settings.py.

Using the statistics plugin
---------------------------

This plugin allows you to collect various statistics about emails
traffic on your server. It parses log file to collect information and
then generates graphics in PNG format.

If you plan to use it, first make sure to have those requirements
installed on your server::

- rrdtool python binding (http://oss.oetiker.ch/rrdtool/)

To activate the extension, edit your settings.py and add the following
line inside the INSTALLED_APPS variable::

  'mailng.extensions.stats',

Create a symbolic link to the templates directory inside the main
templates directory::

  # ln -s <mailng_dir>/extensions/stats/templates \
       templates/stats

Then, adapt following parameters (still in settings.py) to your
environnement::

  # Path to mail log file
  LOGFILE = "/var/log/mail.log"

  # Path to directory where rrd files are stored
  RRD_ROOTDIR = "/tmp/mailng"

  # Path to directory where png files are stored
  IMG_ROOTDIR = "<mailng_dir>/static/graphs"

Make sure the directories that will contain those files exist. If not,
create them before going further. For example (according to previous
parameters)::

  $ mkdir /tmp/mailng
  $ mkdir <mailng_dir>/static/graphs

To finish, you need to collect information periodically in order to
feed rrd files. To do so, just add the following lines into root's
crontab::

  */5 * * * * PYTHONPATH=<mailng_dir/..> DJANGO_SETTINGS_MODULE=mailng.settings <mailng_dir>/extensions/stats/logparser.py

Replace mailng_dir with the installation path of MailNG.

Graphics are automatically created after each new parsing.