modoboa/INSTALL

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

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

- Python version 2.5+
- 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

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.

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

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 t2.full_address FROM admin_alias AS t1, admin_mailbox AS t2 WHERE t1.full_address='%s' AND t1.mbox_id=t2.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 only supports maildir format for now. Others will surely be
added soon.

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

Edit your main Dovecot config file (/etc/dovecot/dovecot.conf) and put 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'

Tips to server 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.