Warning
The new version you are going to install may need to modify your database. Before you start, make sure to backup everything!
Most of the time, upgrading your installation to a newer Modoboa version only requires a few actions. In every case, you will need to apply the general procedure first and then check if the version you are installing requires specific actions.
In case you use a dedicated user and/or a virtualenv, do not forget to use them:
> sudo -i <modoboa_user>
> source <virtuenv_path>/bin/activate
Then, run the following commands:
> pip install modoboa==<VERSION>
> cd <modoboa_instance_dir>
> python manage.py migrate
> python manage.py collectstatic
Once done, check if the version you are installing requires Specific instructions.
Finally, restart your web server.
Sometimes, you might need to upgrade postfix map files too. To do so, just run the generate_postfix_maps command on the same directory than the one used for installation (/etc/postfix by default).
Make sure to use root privileges and run the following command:
> python manage.py generate_postfix_maps --destdir <directory>
Then, reload postfix.
If a new version is available for an extension you’re using, it is recommanded to install it. Upgrading an extensions is pretty and the procedure is almost the same than the one used for Modoboa.
In case you use a dedicated user and/or a virtualenv, do not forget to use them:
> sudo -i <modoboa_user>
> source <virtuenv_path>/bin/activate
Then, run the following commands:
> pip install <EXTENSION>==<VERSION>
> cd <modoboa_instance_dir>
> python manage.py migrate
> python manage.py collectstatic
Finally, restart your web server.
It is a generic upgrade procedure which will be enough most of the time but it is generally a good idea to check the associated documentation.
An interesting feature brougth by this version is the capability to make different checks about MX records. For example, Modoboa can query main DNSBL providers for every defined domain. With this, you will quickly know if one the domains you manage is listed or not. To activate it, add the following line to your crontab:
*/30 * * * * <optional_virtualenv_path/>python <modoboa_instance_dir>/manage.py modo check_mx
The communication with Modoboa public API has been reworked. Instead of sending direct synchronous queries (for example to check new versions), a cron job has been added. To activate it, add the following line to your crontab:
0 * * * * <optional_virtualenv_path/>python <modoboa_instance_dir>/manage.py communicate_with_public_api
Please also note that public API now uses TLS so you must update your configuration as follows:
MODOBOA_API_URL = 'https://api.modoboa.org/1/'
Finally, it is now possible to declare additional sender addresses on a per-account basis. You need to update your postfix configuration in order to use this functionality. Just edit the main.cf file and change the following parameter:
smtpd_sender_login_maps =
<driver>:/etc/postfix/sql-sender-login-mailboxes.cf
<driver>:/etc/postfix/sql-sender-login-aliases.cf
<driver>:/etc/postfix/sql-sender-login-mailboxes-extra.cf
The API has been greatly improved and a documentation is now available. To enable it, add 'rest_framework_swagger' to the INSTALLED_APPS variable in settings.py as follows:
INSTALLED_APPS = (
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.sites',
'django.contrib.staticfiles',
'reversion',
'rest_framework.authtoken',
'rest_framework_swagger',
)
Then, add the following content into settings.py, just after the REST_FRAMEWORK variable:
SWAGGER_SETTINGS = {
"is_authenticated": False,
"api_version": "1.0",
"exclude_namespaces": [],
"info": {
"contact": "contact@modoboa.com",
"description": ("Modoboa API, requires a valid token."),
"title": "Modoboa API",
}
}
You’re done. The documentation is now available at the following address:
http://<your instance address>/docs/api/
Finally, if you find a TEMPLATE_CONTEXT_PROCESSORS variable in your settings.py file, make sure it looks like this:
TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + [
'modoboa.core.context_processors.top_notifications',
]
Warning
Please make sure to use Modoboa 1.3.5 with an up-to-date database before an upgrade to 1.4.0.
Warning
Do not follow the regular upgrade procedure for this version.
Some extension have been moved back into the main repository. The main reason for that is that using Modoboa without them doesn’t make sense.
First of all, you must rename the following applications listed inside the MODOBOA_APPS variable:
Old name | New name |
---|---|
modoboa_admin | modoboa.admin |
modoboa_admin_limits | modoboa.limits |
modoboa_admin_relaydomains | modoboa.relaydomains |
Then, apply the following steps:
Uninstall old extensions:
$ pip uninstall modoboa-admin modoboa-admin-limits modoboa-admin-relaydomains
Install all extension updates using pip (check the Modoboa > Information page)
Manually migrate database:
$ cd <instance_dir>
$ python manage.py migrate auth
$ python manage.py migrate admin 0001 --fake
$ python manage.py migrate admin
$ python manage.py migrate limits 0001 --fake
$ python manage.py migrate relaydomains 0001 --fake
$ python manage.py migrate
Finally, update static files:
$ python manage.py collectstatic
This version also introduces a REST API. To enable it:
Add 'rest_framework.authtoken' to the INSTALLED_APPS variable
Add the following configuration inside settings.py:
# Rest framework settings
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.TokenAuthentication',
),
'DEFAULT_PERMISSION_CLASSES': (
'rest_framework.permissions.IsAuthenticated',
)
}
Run the following command:
$ python manage.py migrate
To enhance security, Modoboa now checks the strength of user passwords <https://github.com/dstufft/django-passwords>_.
To use this feature, add the following configuration into the settings.py file:
# django-passwords
PASSWORD_MIN_LENGTH = 8
PASSWORD_COMPLEXITY = {
"UPPER": 1,
"LOWER": 1,
"DIGITS": 1
}
Modoboa now uses the atomic requests mode to preserve database consistency (reference).
To enable it, update the DATABASES variable in settings.py as follows:
DATABASES = {
"default": {
# stuff before...
"ATOMIC_REQUESTS": True
},
"amavis": {
# stuff before...
"ATOMIC_REQUESTS": True
}
}
This release does not bring awesome new features but it is a necessary bridge to the future of Modoboa. All extensions now have their own git repository and the deploy process has been updated to reflect this change.
Another important update is the use of Django 1.7. Besides its new features, the migration system has been reworked and is now more robust than before.
Before we begin with the procedure, here is a table showing old extension names and their new name:
Old name | New package name | New module name |
---|---|---|
modoboa.extensions.admin | modoboa-admin | modoboa_admin |
modoboa.extensions.limits | modoboa-admin-limits | modoboa_admin_limits |
modoboa.extensions.postfix_autoreply | modoboa-postfix-autoreply | modoboa_postfix_autoreply |
modoboa.extensions.postfix_relay_domains | modoboa-admin-relaydomains | modoboa_admin_relaydomains |
modoboa.extensions.radicale | modoboa-radicale | modoboa_radicale |
modoboa.extensions.sievefilters | modoboa-sievefilters | modoboa_sievefilters |
modoboa.extensions.stats | modoboa-stats | modoboa_stats |
modoboa.extensions.webmail | modoboa-webmail | modoboa_webmail |
Here are the required steps:
Install the extensions using pip (look at the second column in the table above):
$ pip install <the extensions you want>
Remove south from INSTALLED_APPS
Rename old extension names inside MODOBOA_APPS (look at the third column in the table above)
Remove modoboa.lib.middleware.ExtControlMiddleware from MIDDLEWARE_CLASSES
Change DATABASE_ROUTERS to:
DATABASE_ROUTERS = ["modoboa_amavis.dbrouter.AmavisRouter"]
Run the following commands:
$ cd <modoboa_instance_dir>
$ python manage.py migrate
Reply yes to the question
Run the following commands:
$ python manage.py load_initial_data
$ python manage.py collectstatic
The cleanup job has been renamed in Django, so you have to modify your crontab entry:
- 0 0 * * * <modoboa_site>/manage.py cleanup
A new notification service let administrators know about new Modoboa versions. To activate it, you need to update the TEMPLATE_CONTEXT_PROCESSORS variable like this:
from django.conf import global_settings
TEMPLATE_CONTEXT_PROCESSORS = global_settings.TEMPLATE_CONTEXT_PROCESSORS + (
'modoboa.core.context_processors.top_notifications',
)
and to define the new MODOBOA_API_URL variable:
MODOBOA_API_URL = 'http://api.modoboa.org/1/'
The location of external static files has changed. To use them, add a new path to the STATICFILES_DIRS:
# Additional locations of static files
STATICFILES_DIRS = (
# Put strings here, like "/home/html/static" or "C:/www/django/static".
# Always use forward slashes, even on Windows.
# Don't forget to use absolute paths, not relative paths.
"<path/to/modoboa/install/dir>/bower_components",
)
Run the following commands to define the hostname of your instance:
$ cd <modoboa_instance_dir>
$ python manage.py set_default_site <hostname>
If you plan to use the Radicale extension:
Add 'modoboa.extensions.radicale' to the MODOBOA_APPS variable
Run the following commands:
$ cd <modoboa_instance_dir>
$ python manage.py syncdb
Warning
You also have to note that the sitestatic directory has moved from <path to your site's dir> to <modoboa's root url> (it’s probably the parent directory). You have to adapt your web server configuration to reflect this change.