From 5d35fc1edd733f68e18b86f838b85a08dda82ef7 Mon Sep 17 00:00:00 2001
From: Antoine Nguyen <tonio@ngyn.org>
Date: Fri, 24 Jun 2011 12:10:58 +0200
Subject: [PATCH] Documentation update (added a dedicated section to explain
 how to migrate from PostfixAdmin).

---
 INSTALL     | 85 ++++++++++++++++++++++++++++++++++++++++++++++-------
 doc/conf.py |  4 +--
 2 files changed, 77 insertions(+), 12 deletions(-)

diff --git a/INSTALL b/INSTALL
index f40314f0b..5afa15d1b 100644
--- a/INSTALL
+++ b/INSTALL
@@ -4,7 +4,7 @@ Installation
 Requirements
 ============
 
-- Python version 2.6+
+- `Python version 2.6+ <http://python.org/>`_
 - `Django version 1.2+ <http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_
 - `south version 0.7+ <http://south.aeracode.org/>`_
 
@@ -17,6 +17,8 @@ For extensions (mandatories since 0.8.2):
 - `ckeditor version 3.4.1+ <http://ckeditor.com/>`_
 - `sievelib python module <http://pypi.python.org/pypi/sievelib>`_
 
+.. _howtoinstall:
+
 How to install
 ==============
 
@@ -41,10 +43,10 @@ Initialize the database by running the following command::
   $ python manage.py syncdb
 
 It will let you create the default super administrator.
-S
-ince version 0.8, Modoboa is using *south* to handle schema
-migrations. To finish the database initialization, you must
-apply existing migrations like this::
+
+Since version 0.8, Modoboa is using *south* to handle schema
+migrations. To finish the database initialization, you must apply
+existing migrations like this::
 
   $ python manage.py migrate
 
@@ -183,9 +185,12 @@ requires a migration.
       'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware',
     )
 
-#. Go the *Settings/Extensions* panel, deactivate and activate your extensions, it will update all the symbolic links to the new format.
+#. Go the *Settings/Extensions* panel, deactivate and activate your
+   extensions, it will update all the symbolic links to the new format.
 
-#. Optional: update the ``DATABASES`` and ``TEMPLATE_LOADERS`` variables in *settings.py* to remove warning messages (appearing with Django 1.3)::
+#. Optional: update the ``DATABASES`` and ``TEMPLATE_LOADERS``
+   variables in *settings.py* to remove warning messages (appearing with
+   Django 1.3)::
 
     DATABASES = {
       "default" : {
@@ -210,9 +215,11 @@ requires a migration.
 
      $ python manage.py migrate admin
 
-#. Update SQL queries used in your environnement (see :ref:`postfix-label` or :ref:`dovecot-label`).
+#. Update SQL queries used in your environnement (see
+   :ref:`postfix-label` or :ref:`dovecot-label`).
 
-#. Update *postfix* configuration so that it can handle domain aliases (see :ref:`postfix-label`).
+#. Update *postfix* configuration so that it can handle domain aliases
+   (see :ref:`postfix-label`).
 
 
 0.8.2: ckeditor integration and more
@@ -562,7 +569,65 @@ PostfixAdmin
 ------------
 
 Since version 0.8.5, Modoboa provides a simple script to migrate an
-existing PostfixAdmin database to a Modoboa one.
+existing `PostfixAdmin (version 2.3.3+)
+<http://postfixadmin.sourceforge.net/>`_ database to a Modoboa one.
+
+.. note::
+   This script is only suitable for a new installation.
+
+First, you must follow the :ref:`howtoinstall` step to create a fresh
+Modoboa database.
+
+Once done, edit the *setting.py* file. First, add a new database
+connection named ``pfxadmin`` into the ``DATABASES`` variable
+corresponding to your PostfixAdmin setup::
+
+  DATABASES = {
+    "default" : {
+      # default connection definition
+    },
+    "pfxadmin" : {
+      "ENGINE" : "<engine>",
+      "NAME" : "<database name>",
+      "USER" : "<database user>",
+      "PASSWORD" : "<user password>",
+    }  
+  }
+
+This connection should correspond to the one defined in PostfixAdmin's
+configuration file. Then, add ``'modoboa.tools.pfxadmin_migrate',`` to
+the ``INSTALLED_APPS`` variable. Save your modifications.
+
+You are now ready to start the migration. Enter Modoboa's root
+directory and execute the following command::
+
+  $ PYTHONPATH=$PWD/.. DJANGO_SETTINGS_MODULE=modoboa.settings \
+      ./tools/pfxadmin_migrate/migrate.py -r -p <directory that stores mailboxes>
+
+Depending on how many domains/mailboxes your existing setup contains,
+the migration can be long. Just wait for the script's ending.
+
+Once the migration has succeed, go the *Admin > Configuration* panel,
+click on the *admin* row and modify the value of ``MAILDIR_ROOT`` as
+follow::
+
+  MAILDIR_ROOT =
+
+The corresponding field must be empty. Don't touch other fields except
+``PASSWORD_SCHEME``, if needed. (set it to the same method as the one
+used by PostfixAdmin, check its configuration file if you're not sure)
+
+Click on the *Save* button.
+
+The procedure is over, edit the *settings.py* file and:
+
+* remove the ``pfxadmin`` database connection from the ``DATABASES``
+  variable
+* remove the ``'modoboa.tools.pfxadmin_migrate',`` from the
+  ``INSTALLED_APPS`` variable
+
+You should be able to connect to Modoboa using the same credentials
+you were using to connect to PostfixAdmin.
 
 How to serve Modoboa behind a webserver
 =======================================
diff --git a/doc/conf.py b/doc/conf.py
index 8fb44f0e3..8fa6c3c89 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -48,9 +48,9 @@ copyright = u'2011, Antoine Nguyen'
 # built documents.
 #
 # The short X.Y version.
-version = '0.8.4'
+version = '0.8.5'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.4'
+release = '0.8.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.