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.
Warning
If you use a version prior to 0.9.5, please migrate in two steps:
- first migrate to 0.9.5
- then migrate to the latest version
If you try to migrate directly, the operation will fail.
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
Warning
If you migrate to 1.1.0, please follow the dedicated migration
procedure <1.1.0>
and skip the usual one.
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
For those who installed Dovecot in a non-standard location, it is now possible to tell Modoboa where to find it. Just define a variable named DOVECOT_LOOKUP_PATH
in the settings.py
file and include the appropriate lookup path inside:
DOVECOT_LOOKUP_PATH = ("/usr/sbin/dovecot", "/usr/local/sbin/dovecot")
Due to code refactoring, some modifications need to be done into settings.py
:
MODOBOA_APPS
must contain the following applications:MODOBOA_APPS = ( 'modoboa', 'modoboa.core', 'modoboa.lib', 'modoboa.extensions.admin', 'modoboa.extensions.limits', 'modoboa.extensions.postfix_autoreply', 'modoboa.extensions.webmail', 'modoboa.extensions.stats', 'modoboa.extensions.amavis', 'modoboa.extensions.sievefilters', )
- Add
'modoboa.extensions.postfix_relay_domains'
toMODOBOA_APPS
, just before'modoboa.extensions.limits'
AUTH_USER_MODEL
must be set tocore.User
- Into
LOGGING
, replacemodoboa.lib.logutils.SQLHandler
bymodoboa.core.loggers.SQLHandler
Then, run the following commands to migrate your installation:
$ python manage.py syncdb
$ python manage.py migrate core 0001 --fake
$ python manage.py migrate
$ python manage.py collectstatic
Finally, update both Dovecot <dovecot_authentication>
and Postfix <postfix>
queries.
The way Modoboa handles rename and delete operations on mailboxes has been improved. Make sure to consult fs_operations
and Postfix configuration <postfix_config>
. Look at the smtpd_recipient_restrictions
setting.
Run modoboa-admin.py postfix_maps --dbtype <mysql|postgres|sqlite> <tempdir>
and compare the files with those that postfix currently use. Make necessary updates in light of the differences
Several modifications need to be done into settings.py
.
Add the following import statement:
from logging.handlers import SysLogHandler
Set the
ALLOWER_HOSTS
variable:ALLOWED_HOSTS = [ '<your server fqdn>', ]
Activate the
django.middleware.csrf.CsrfViewMiddleware
middleware and add thereversion.middleware.RevisionMiddleware
middleware toMIDDLEWARE_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', )
- Add the
reversion
application toINSTALLED_APPS
Remove all modoboa's application from
INSTALLED_APPS
and put them into the newMODOBOA_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
Set the
AUTH_USER_MODEL
variable like this:AUTH_USER_MODEL = 'admin.User'
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 } } }
It is necessary to update the queries used to retrieve users and mailboxes:
- Run
modoboa-admin.py postfix_maps --dbtype <mysql|postgres> <tempdir>
and compare the files with those that postfix currently use. Make necessary updates in light of the differences - Into
dovecot-sql.conf
, update theuser_query
query, refer todovecot_mysql_queries
ordovecot_pg_queries
- Update dovecot's configuration to activate the new
quota related features <dovecot_quota>
When running the python manage.py syncdb --migrate
command, you may encounter the following issues:
Remove useless content types
If the script asks you this question, just reply no.
South fails to migrate
reversion
Due to the admin user model change, the script
0001_initial.py
may fail. Just deactivatereversion
fromINSTALLED_APPS
and run the command again. Once done, reactivatereversion
and run the command one last time.
- Edit the
settings.py
file and remove'django.contrib.auth.backends.ModelBackend'
from theAUTHENTICATION_BACKENDS
variable
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:
- The
media
directory - The directory containing RRD files if you use the
stats
plugin
Don't copy the old settings.py
file, just keep the new one and modify it (see database
and timezone_lang
).
Migrate your database (see latestversion
).
Finally, check the amavis_frontend
, postfix_ar
and stats
chapters (depending on those you use) because the provided cron scripts have been changed, you must update the way you call them.
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.
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!
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', )
- Add
django.contrib.staticfiles
toINSTALLED_APPS
Add the following new variables:
STATIC_ROOT = os.path.join(MODOBOA_DIR, 'sitestatic') STATIC_URL = '/sitestatic/'
Update the following variables (just copy/paste their new values):
MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'media') MEDIA_URL = '/media/'
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;", }, } }
- Add
'modoboa.extensions.limits'
toINSTALLED_APPS
Update your database (make sure to create a backup before launching the following command):
$ ./manage.py syncdb --migrate
Run the following command to initialize the directory that contains static files:
$ ./manage.py collectstatic
- 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 theIMG_ROOTDIR
parameter (go to the adminstration panel) - Restart the python instance(s) that serve Modoboa
- Log into Modoboa, go to Modoboa > Extensions, uncheck all extensions, save. Then, check the extensions you want to use and save again
- Update your webserver configuration to make static files available (see
webservers
) 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'
Edit the
settings.py
file and add'modoboa.lib.middleware.AjaxLoginRedirect'
to theMIDDLEWARE_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', )
Still inside
settings.py
, modify theDATABASE_ROUTERS
variable like this:DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"]
Edit the
settings.py
file and add the'django.middleware.locale.LocaleMiddleware'
middleware to theMIDDLEWARE_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', )
- 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.
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
Just update your configuration if you are using the quarantine plugin. Open
settings.py
, move the database configuration from theDB_CONNECTIONS
variable to theDATABASES
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>" } }
Add the new following variable somewhere in the file:
DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"]
- Remove the deprecated
DB_CONNECTIONS
variable fromsettings.py
.
Migrate the
lib
andadmin
applications:$ python manage.py migrate lib $ python manage.py migrate admin
- Add
modoboa.auth
andmodoboa.extensions.sievefilters
to theINSTALLED_APPS
variable insettings.py
. - Go the Settings/Extensions panel, deactivate and activate your extensions, it will update all the symbolic links.
Update the
MIDDLEWARE_CLASSES
variable insettings.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', )
- 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
andTEMPLATE_LOADERS
variables insettings.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', )
Migrate the
admin
application:$ python manage.py migrate admin
- Update SQL queries used in your environnement (see
postfix
ordovecot
). - Update Postfix configuration so that it can handle domain aliases (see
postfix
).
Migrate the admin applicaton:
$ python manage.py migrate admin
- Update your config file and add all extensions to
INSTALLED_APPS
(even those you are not going to use). - Inside the
<modoboa_dir>/templates/
directory, remove all symbolic links. - Download the latest release of ckeditor and extract it into
<modoboa_dir>/static/js/
. It should create a new directory namedckeditor
. Update the following variables inside
settings.py
:MEDIA_ROOT = os.path.join(MODOBOA_DIR, 'static') MEDIA_URL = '/static/'
- Then, add the following variable:
MODOBOA_WEBPATH = 'modoboa/'
- Delete the following variables:
STATIC_ROOTDIR
andTEMPLATE_CONTEXT_PROCESSORS
. - Finally, add
modoboa.lib.middleware.ExtControlMiddleware
toMIDDLEWARE_CLASSES
.
- First, rename the
mailng
directory tomodoboa
and copy all the content frommodoboa-0.8.1
tomodoboa
. - Edit
settings.py
and replace all occurences of mailng by modoboa. Make sure you don't modify theDATABASE
section as you're not going to rename your database. - Rename the
MAILNG_DIR
variable toMODOBOA_DIR
. - Add
'django.contrib.messages.middleware.MessageMiddleware'
toMIDDLEWARE_CLASSES
and'django.contrib.messages'
toINSTALLED_APPS
. Save your modifications. Run the following command:
$ python manage.py syncdb
For all activated extensions, run the following command:
$ export PYTHONPATH=<modoboa_dir>/..= $ DJANGO_SETTINGS_MODULE=modoboa.settings <modoboa_dir>/scripts/extension.py <extension> on
- Update your webserver configuration and restart it.
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