github-jwinterm/modoboa
1
0
Fork 0
mirror of https://github.com/jwinterm/modoboa.git synced 2026-10-18 05:51:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation update.

Browse Source 
see #649
This commit is contained in:
Antoine Nguyen
2014-12-10 15:43:45 +01:00
parent bf32aa20e8
commit efa586dba9
5 changed files with 43 additions and 415 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/extending/getting_started.rst
+1 -1
View File
@@ -42,7 +42,7 @@ Deploy an instance for development
Now that you have a :ref:`running environment <venv_for_dev>`, you're
ready to deploy a test instance::
$ modoboa-admin.py deploy --syncdb --devel --dburl <database url> <path>
$ modoboa-admin.py deploy --dbaction install --devel --dburl <database url> <path>
$ cd <path>
$ python manage.py runserver
doc/getting_started/install.rst
+8 -4
View File
@@ -9,7 +9,7 @@ Requirements
************
* `Python version 2.6+ <http://python.org/>`_
* `Django version 1.5+ <http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_
* `Django version 1.6+ <http://docs.djangoproject.com/en/dev/intro/install/#intro-install>`_
* `south version 0.7+ <http://south.aeracode.org/>`_
* `lxml python module <http://lxml.de/installation.html>`_
* `pycrypto python module <http://www.dlitz.net/software/pycrypto/>`_
@@ -94,7 +94,7 @@ Deployment
`modoboa-admin.py`, a command line tool, lets you deploy a
*ready-to-use* Modoboa site using only one instruction::
$ modoboa-admin.py deploy modoboa_example --syncdb --collectstatic [--with-amavis] [--dburl database-url] [--amavis_dburl database-url]
$ modoboa-admin.py deploy modoboa_example --dbaction install --collectstatic [--with-amavis] [--dburl database-url] [--amavis_dburl database-url]
Just answer the few questions and you're done. You can now go to the
:ref:`first_use` section.
@@ -103,10 +103,14 @@ Just answer the few questions and you're done. You can now go to the
The `--with-amavis` option must be set only if you intend to use
the :ref:`amavis_frontend`.
In case you need a **silent installation** (e.g. if you're using
Salt-Stack, Ansible or whatever), it's possible to supply the database
credentials as commandline arguments.
You can see the complete option list by running the following command::
In case you need a **silent installation**, e.g. if you're using Salt-Stack.
It's possible to supply the database credentials as commandline arguments.
$ modoboa-admin.py help deploy
.. note::
doc/getting_started/upgrade.rst
+20 -403
View File
@@ -15,21 +15,8 @@ newest versions of Modoboa.
Latest version
**************
.. 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 :ref:`get_modoboa`) and
install it.
``pip`` users, just run the following command::
Fetch the latest version (see :ref:`get_modoboa`) and install
it. ``pip`` users, just run the following command::
$ pip install modoboa==<VERSION>
@@ -40,47 +27,30 @@ Replace ``<VERSION>`` by the appropriate value.
If you migrate to **1.1.0**, please follow the :ref:`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.
As for a fresh installation, ``modoboa-admin.py`` is used to upgrade
your local configuration. To do so, remove the directory where your
instance was first deployed::
Then, follow the common procedure::
$ rm -rf <modoboa_instance_dir>
$ cd <modoboa_instance_dir>
$ python manage.py syncdb --migrate
$ python manage.py collectstatic
If you customized your configuration file (:file:`settings.py`) with
non-standard settings, you'll have to re-apply them.
Eventually, restart the web server process according to the environment
Then, run ``modoboa-admin.py deploy``::
$ modoboa-admin.py deploy <modoboa_instance_dir> --dbaction upgrade --collectstatic [--with-amavis] [--dburl database-url] [--amavis_dburl database-url] [--domain hostname] [--lang lang] [--timezone timezone]
According to the version you're installing, check if
:ref:`specific_upgrade_instructions` are required.
To finish, restart the web server process according to the environment
you did choose. See :ref:`webservers` for more details.
1.2.0: radicale extension, bootstrap3 and more
==============================================
.. _specific_upgrade_instructions:
A new notification service let administrators know about new Modoboa
versions. To activate it, you need to:
#. Add `'modoboa.core.context_processors.top_notifications'`` to the
``TEMPLATE_CONTEXT_PROCESSORS`` variable
#. 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",
)
#. Define the ``MODOBOA_API_URL`` variable::
MODOBOA_API_URL = 'http://api.modoboa.org/1/'
#. Run the following commands to define the hostname of your
instance::
$ cd <modoboa_instance_dir>
$ python manage.py set_default_site <hostname>
*****************************
Specific upgrade instructions
*****************************
1.1.7: manual learning for SpamAssassin
=======================================
@@ -338,356 +308,3 @@ may encounter the following issues:
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
================================================
#. Edit the :file:`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
:ref:`deployment`) in a different directory.
Then, copy the following content from the old installation to the new
one:
* The :file:`media` directory
* The directory containing RRD files if you use the :ref:`stats` plugin
Don't copy the old :file:`settings.py` file, just keep the new one and
modify it (see :ref:`database` and :ref:`timezone_lang`).
Migrate your database (see :ref:`latestversion`).
Finally, check the :ref:`amavis_frontend`, :ref:`postfix_ar` and
:ref:`stats` 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. :file:`/tmp` for example). Then, remove the :file:`modoboa` directory,
extract the new tarball at the same place, rename the new directory
to :file:`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 :file:`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`` to ``INSTALLED_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'`` to ``INSTALLED_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
:file:`<modoboa_dir>/static/stats` directory to :file:`<modoboa_dir>/media/stats`
and change the value of the ``IMG_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 :ref:`webservers`)
#. **For Dovecot users only**, you need to modify the
``password_query`` (file :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
=========================================
#. Edit the :file:`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',
)
#. Still inside :file:`settings.py`, modify the ``DATABASE_ROUTERS``
variable like this::
DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"]
0.8.7: per-user language selection
==================================
#. Edit the :file:`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',
)
#. 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
============================
#. If you have tried to create a new mailbox and if you have
encountered the following `issue
<http://dev.modoboa.org/ticket/163>`_, 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)
=========================================================
#. Just update your configuration if you are using the quarantine
plugin. Open :file:`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>"
}
}
#. Add the new following variable somewhere in the file::
DATABASE_ROUTERS = ["modoboa.extensions.amavis_quarantine.dbrouter.AmavisRouter"]
#. Remove the deprecated ``DB_CONNECTIONS`` variable from :file:`settings.py`.
0.8.5: new "Sieve filters" plugin, improved admin app
=====================================================
#. Migrate the ``lib`` and ``admin`` applications::
$ python manage.py migrate lib
$ python manage.py migrate admin
#. Add ``modoboa.auth`` and ``modoboa.extensions.sievefilters`` to the
``INSTALLED_APPS`` variable in :file:`settings.py`.
#. 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
==========================================================
#. Update the ``MIDDLEWARE_CLASSES`` variable in :file:`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',
)
#. 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 :file:`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
=============================================
#. Migrate the ``admin`` application::
$ python manage.py migrate admin
#. Update SQL queries used in your environment (see
:ref:`postfix` or :ref:`dovecot`).
#. Update Postfix configuration so that it can handle domain aliases
(see :ref:`postfix`).
0.8.2: ckeditor integration and more
====================================
#. 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 :file:`<modoboa_dir>/templates/` directory, remove all symbolic links.
#. Download the latest release of ckeditor and extract it into :file:`<modoboa_dir>/static/js/`. It should create a new directory named ``ckeditor``.
#. Update the following variables inside :file:`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`` and
``TEMPLATE_CONTEXT_PROCESSORS``.
#. Finally, add ``modoboa.lib.middleware.ExtControlMiddleware`` to
``MIDDLEWARE_CLASSES``.
0.8.1 : project renamed
=======================
#. First, rename the ``mailng`` directory to ``modoboa`` and copy all the
content from ``modoboa-0.8.1`` to ``modoboa``.
#. Edit :file:`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.
#. Rename the ``MAILNG_DIR`` variable to ``MODOBOA_DIR``.
#. Add ``'django.contrib.messages.middleware.MessageMiddleware'`` to
``MIDDLEWARE_CLASSES`` and ``'django.contrib.messages'`` to
``INSTALLED_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.
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
modoboa/core/commands/deploy.py
+8 -3
View File
@@ -47,8 +47,8 @@ class DeployCommand(Command):
help='Include amavis configuration'
)
self._parser.add_argument(
'--syncdb', action='store_true', default=False,
help='Run django syncdb command'
'--dbaction', type=str, default="install",
help='Action to take on the database (install|upgrade)'
)
self._parser.add_argument(
'--collectstatic', action='store_true', default=False,
@@ -216,7 +216,7 @@ class DeployCommand(Command):
)
os.mkdir("%s/media" % path)
if parsed_args.syncdb:
if parsed_args.dbaction == "install":
os.unlink("%s/settings.pyc" % path)
self._exec_django_command(
"syncdb", parsed_args.name, '--noinput'
@@ -231,6 +231,11 @@ class DeployCommand(Command):
self._exec_django_command(
"loaddata", parsed_args.name, 'initial_users.json'
)
elif parsed_args.dbaction == "upgrade":
exec_cmd('sed -ri "s|^#(\s+\'south)|\\1|" %s/settings.py' % path)
self._exec_django_command(
"syncdb", parsed_args.name, "--migrate"
)
if parsed_args.collectstatic:
self._exec_django_command(
tests/install_from_scratch.py
+6 -4
View File
@@ -35,8 +35,10 @@ class DeployTest(unittest.TestCase):
def test_standard(self):
timeout = 2
cmd = "modoboa-admin.py deploy --syncdb --collectstatic {0}".format(
self.projname)
cmd = (
"modoboa-admin.py deploy --dbaction install --collectstatic {0}"
.format(self.projname)
)
child = pexpect.spawn(cmd, cwd=self.workdir)
fout = open('install_from_scratch.log', 'w')
child.logfile = fout
@@ -63,8 +65,8 @@ class DeployTest(unittest.TestCase):
% (self.dbtype, self.dbuser, self.dbpassword,
self.dbhost, self.projname)
cmd = (
"modoboa-admin.py deploy --syncdb --collectstatic --dburl %s "
"--extensions all --domain %s %s"
"modoboa-admin.py deploy --dbaction install --collectstatic "
"--dburl %s --extensions all --domain %s %s"
% (dburl, 'localhost', self.projname)
)
code, output = exec_cmd(cmd, cwd=self.workdir)