Upgrading an existing installation

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.

Latest version

Starting with version 0.9.1, Modoboa comes as a standard django application. Fetch the latest version (see Get Modoboa) and install it.

pip users, just run the following command:

$ pip install --upgrade modoboa

Then, 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.

Finally, follow the common procedure:

$ cd <modoboa_instance_dir>
$ python manage.py syncdb --migrate
$ python manage.py collectstatic

1.0.0: production ready, at last

Configuration file update

Several modifications need to be done into settings.py.

  1. Add the following import statement:

    from logging.handlers import SysLogHandler
    
  2. Set the ALLOWER_HOSTS variable:

    ALLOWED_HOSTS = [
        '<your server fqdn>',
    ]
    
  3. 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',
    )
    
  4. Add the reversion application to INSTALLED_APPS

  5. 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
    
  6. Set the AUTH_USER_MODEL variable like this:

    AUTH_USER_MODEL = 'admin.User'
    
  7. 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:

  1. Replace all occurences of auth_user by admin_user
  2. Into dovecot-sql.conf, update the user_query query, refer to MySQL users or PostgreSQL users
  3. Update dovecot’s configuration to activate the new quota related features

Migration issues

When running the python manage.py syncdb --migrate command, you may encounter the following issues:

  1. Remove useless content types

    If the script asks you this question, just reply no.

  2. South fails to migrate reversion

    Due to the admin user model change, the script 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.

0.9.4: administrative panel performance improved

  1. Edit the settings.py file and remove 'django.contrib.auth.backends.ModelBackend' from the AUTHENTICATION_BACKENDS variable

0.9.1: standard django application and more

For this version, we recommend to install a new instance (see Deployment) in a different directory.

Then, copy the following content from the old installation to the new one:

Don’t copy the old settings.py file, just keep the new one and modify it (see Database and Time zone and language).

Migrate your database (see Latest version).

Finally, check the Amavisd-new frontend, Postifx auto-reply messages and Graphical statistics chapters (depending on those you use) because the provided cron scripts have been changed, you must update the way you call them.

Modoboa 0.9 and prior

First, decompress the new tarball at the same location than your current installation. Then, check if the new version you’re installing requires a migration.

0.9: global UI refactoring, new limits extension and more

Note

This version requires at least django 1.3. Make sure to update your version before starting to migrate.

Note

Many files have been renamed/removed for this version. I recommend that you backup important files (settings.py, etc.) elsewhere (ie. /tmp for example). Then, remove the modoboa directory, extract the new tarball at the same place, rename the new directory to modoboa and copy the files you’ve just backup into it.

Note

If the first super administrator you created is named admin, its password will be changed to password at the end of this upgrade. Don’t forget to modify it!

  1. Edit the settings.py file and update the following variables (just copy/paste their new content):

    MIDDLEWARE_CLASSES = (
        'django.middleware.common.CommonMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.messages.middleware.MessageMiddleware',
        'django.middleware.locale.LocaleMiddleware',
        'modoboa.lib.middleware.AjaxLoginRedirect',
        'modoboa.lib.middleware.CommonExceptionCatcher',
        'modoboa.lib.middleware.ExtControlMiddleware',
    )
    
    AUTHENTICATION_BACKENDS = (
        'modoboa.lib.authbackends.SimpleBackend',
        'django.contrib.auth.backends.ModelBackend',
    )
    
  2. Add django.contrib.staticfiles to INSTALLED_APPS

  3. Add the following new variables:

    STATIC_ROOT = os.path.join(MODOBOA_DIR, 'sitestatic')
    STATIC_URL = '/sitestatic/'
    
  4. Update the following variables (just copy/paste their new values):

    MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'media')
    MEDIA_URL = '/media/'
    
  5. For MySQL users only, add the following option to your database configuration:

    DATABASES = {
        "default" : {
            # ...
            # MySQL users only
            "OPTIONS" : {
                "init_command" : "SET foreign_key_checks = 0;",
            },
        }
    }
    
  6. Add 'modoboa.extensions.limits' to INSTALLED_APPS

  7. Update your database (make sure to create a backup before launching the following command):

    $ ./manage.py syncdb --migrate
  8. Run the following command to initialize the directory that contains static files:

    $ ./manage.py collectstatic
  9. If you are using the stats extension, please rename the <modoboa_dir>/static/stats directory to <modoboa_dir>/media/stats and change the value of the IMG_ROOTDIR parameter (go to the adminstration panel)

  10. Restart the python instance(s) that serve Modoboa

  11. Log into Modoboa, go to Modoboa > Extensions, uncheck all extensions, save. Then, check the extensions you want to use and save again

  12. Update your webserver configuration to make static files available (see Web servers)

  13. For Dovecot users only, you need to modify the password_query (file /etc/dovecot/dovecot-sql.conf by default on a Debian system) like this:

    password_query = SELECT email AS user, password FROM auth_user WHERE email='%u'

0.8.8: CSV import feature and minor fixes

  1. Edit the settings.py file and add 'modoboa.lib.middleware.AjaxLoginRedirect' to the MIDDLEWARE_CLASSES variable like this:

    MIDDLEWARE_CLASSES = (
      'django.middleware.common.CommonMiddleware',
      'django.contrib.sessions.middleware.SessionMiddleware',
      'django.contrib.auth.middleware.AuthenticationMiddleware',
      'django.contrib.messages.middleware.MessageMiddleware',
      'django.middleware.locale.LocaleMiddleware',
      'modoboa.lib.middleware.AjaxLoginRedirect',
      'modoboa.lib.middleware.ExtControlMiddleware',
      'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware',
    )
    
  2. Still inside settings.py, modify the DATABASE_ROUTERS variable like this:

    DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"]
    

0.8.7: per-user language selection

  1. Edit the settings.py file and add the 'django.middleware.locale.LocaleMiddleware' middleware to the MIDDLEWARE_CLASSES variable like this:

    MIDDLEWARE_CLASSES = (
      'django.middleware.common.CommonMiddleware',
      'django.contrib.sessions.middleware.SessionMiddleware',
      'django.contrib.auth.middleware.AuthenticationMiddleware',
      'django.contrib.messages.middleware.MessageMiddleware',
      'django.middleware.locale.LocaleMiddleware',
      'modoboa.lib.middleware.ExtControlMiddleware',
      'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware',
    )
    
  2. To select a custom language, go to Options > Preferences and select the general section. Choose a value, save and disconnect from Modoboa. On the next login, the desired language will be used.

0.8.6.1: maintenance release

  1. If you have tried to create a new mailbox and if you have encountered the following issue, you must run the dbcleanup.py script in order to remove orphan records:

    $ cd <modoboa_dir>
    $ PYTHONPATH=$PWD/.. DJANGO_SETTINGS_MODULE=modoboa.settings ./admin/scripts/dbcleanup.py

0.8.6: Quarantine plugin refactoring (using Django’s ORM)

  1. Just update your configuration if you are using the quarantine plugin. Open settings.py, move the database configuration from the DB_CONNECTIONS variable to the DATABASES variable, like this:

    DATABASES = {
        "default" : {
            # The default database configuration
        },
        #    ...
        "amavis": {
            "ENGINE" : "<your value>",
            "HOST" : "<your value>",
            "NAME" : "<your value>",
            "USER" : "<your value>",
            "PASSWORD" : "<your value>"
        }
    }
    
  2. Add the new following variable somewhere in the file:

    DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"]
    
  3. Remove the deprecated DB_CONNECTIONS variable from settings.py.

0.8.5: new “Sieve filters” plugin, improved admin app

  1. Migrate the lib and admin applications:

    $ python manage.py migrate lib
    $ python manage.py migrate admin
  2. Add modoboa.auth and modoboa.extensions.sievefilters to the INSTALLED_APPS variable in settings.py.

  3. Go the Settings/Extensions panel, deactivate and activate your extensions, it will update all the symbolic links.

0.8.4: folders manipulation support (webmail) and bugfixes

  1. Update the MIDDLEWARE_CLASSES variable in settings.py:

    MIDDLEWARE_CLASSES = (
      'django.middleware.common.CommonMiddleware',
      'django.contrib.sessions.middleware.SessionMiddleware',
      'django.contrib.auth.middleware.AuthenticationMiddleware',
      'django.contrib.messages.middleware.MessageMiddleware',
      'modoboa.lib.middleware.ExtControlMiddleware',
      'modoboa.extensions.webmail.middleware.WebmailErrorMiddleware',
    )
    
  2. Go the Settings/Extensions panel, deactivate and activate your extensions, it will update all the symbolic links to the new format.

  3. Optional: update the DATABASES and TEMPLATE_LOADERS variables in settings.py to remove warning messages (appearing with Django 1.3):

    DATABASES = {
      "default" : {
        "ENGINE" : "<your engine>",
        "NAME" : "modoboa",
        "USER" : "<your user>",
        "PASSWORD" : "<your password>",
        "HOST" : "",
        "PORT" : ""
      }
    }
    
    TEMPLATE_LOADERS = (
      'django.template.loaders.filesystem.Loader',
      'django.template.loaders.app_directories.Loader',
    )
    

0.8.3: admin application refactoring and more

  1. Migrate the admin application:

    $ python manage.py migrate admin
  2. Update SQL queries used in your environnement (see Postfix or Dovecot).

  3. Update postfix configuration so that it can handle domain aliases (see Postfix).

0.8.2: ckeditor integration and more

  1. Migrate the admin applicaton:

    $ python manage.py migrate admin
  2. Update your config file and add all extensions to INSTALLED_APPS (even those you are not going to use).

  3. Inside the <modoboa_dir>/templates/ directory, remove all symbolic links.

  4. Download the latest release of ckeditor and extract it into <modoboa_dir>/static/js/. It should create a new directory named ckeditor.

  5. Update the following variables inside settings.py:

    MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'static')
    MEDIA_URL = '/static/'
    
  6. Then, add the following variable: MODOBOA_WEBPATH = 'modoboa/'

  7. Delete the following variables: STATIC_ROOTDIR and TEMPLATE_CONTEXT_PROCESSORS.

  8. Finally, add modoboa.lib.middleware.ExtControlMiddleware to MIDDLEWARE_CLASSES.

0.8.1 : project renamed

  1. First, rename the mailng directory to modoboa and copy all the content from modoboa-0.8.1 to modoboa.

  2. Edit settings.py and replace all occurences of mailng by modoboa. Make sure you don’t modify the DATABASE section as you’re not going to rename your database.

  3. Rename the MAILNG_DIR variable to MODOBOA_DIR.

  4. Add 'django.contrib.messages.middleware.MessageMiddleware' to MIDDLEWARE_CLASSES and 'django.contrib.messages' to INSTALLED_APPS. Save your modifications.

  5. Run the following command:

    $ python manage.py syncdb
  6. For all activated extensions, run the following command:

    $ export PYTHONPATH=<modoboa_dir>/..=
    $ DJANGO_SETTINGS_MODULE=modoboa.settings <modoboa_dir>/scripts/extension.py <extension> on
  7. Update your webserver configuration and restart it.

0.8 : SQL migration needed

Before you start the migration, make sure you have updated your INSTALLED_APPS variable and that it contains at least:

INSTALLED_APPS = (
   # Django's stuff before

   'south',
   'mailng',
   'mailng.lib',
   'mailng.admin',
   'mailng.userprefs',
)

Starting with 0.8, mailng.main doesn’t exist anymore. You must remove it from your INSTALLED_APPS.

Finally, 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