From efa586dba9bec958cc0f2a48dfc773f826a6977a Mon Sep 17 00:00:00 2001 From: Antoine Nguyen Date: Wed, 10 Dec 2014 15:43:45 +0100 Subject: [PATCH] Documentation update. see #649 --- doc/extending/getting_started.rst | 2 +- doc/getting_started/install.rst | 12 +- doc/getting_started/upgrade.rst | 423 ++---------------------------- modoboa/core/commands/deploy.py | 11 +- tests/install_from_scratch.py | 10 +- 5 files changed, 43 insertions(+), 415 deletions(-) diff --git a/doc/extending/getting_started.rst b/doc/extending/getting_started.rst index cde42354e..7e773d1fe 100644 --- a/doc/extending/getting_started.rst +++ b/doc/extending/getting_started.rst @@ -42,7 +42,7 @@ Deploy an instance for development Now that you have a :ref:`running environment `, you're ready to deploy a test instance:: - $ modoboa-admin.py deploy --syncdb --devel --dburl + $ modoboa-admin.py deploy --dbaction install --devel --dburl $ cd $ python manage.py runserver diff --git a/doc/getting_started/install.rst b/doc/getting_started/install.rst index 7d3117c27..b8b12f323 100644 --- a/doc/getting_started/install.rst +++ b/doc/getting_started/install.rst @@ -9,7 +9,7 @@ Requirements ************ * `Python version 2.6+ `_ -* `Django version 1.5+ `_ +* `Django version 1.6+ `_ * `south version 0.7+ `_ * `lxml python module `_ * `pycrypto python module `_ @@ -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:: diff --git a/doc/getting_started/upgrade.rst b/doc/getting_started/upgrade.rst index 5bf536631..127020951 100644 --- a/doc/getting_started/upgrade.rst +++ b/doc/getting_started/upgrade.rst @@ -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== @@ -40,47 +27,30 @@ Replace ```` 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 - $ cd - $ 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 --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. - "/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 - $ python manage.py set_default_site +***************************** +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:`/static/stats` directory to :file:`/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 - `_, you must run the - ``dbcleanup.py`` script in order to remove orphan records:: - - $ cd - $ 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" : "", - "HOST" : "", - "NAME" : "", - "USER" : "", - "PASSWORD" : "" - } - } - -#. 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" : "", - "NAME" : "modoboa", - "USER" : "", - "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:`/templates/` directory, remove all symbolic links. -#. Download the latest release of ckeditor and extract it into :file:`/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=/..= - $ DJANGO_SETTINGS_MODULE=modoboa.settings /scripts/extension.py 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 - diff --git a/modoboa/core/commands/deploy.py b/modoboa/core/commands/deploy.py index c47df68cf..cb1b4cb01 100644 --- a/modoboa/core/commands/deploy.py +++ b/modoboa/core/commands/deploy.py @@ -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( diff --git a/tests/install_from_scratch.py b/tests/install_from_scratch.py index d45d45e95..9fafbb56c 100644 --- a/tests/install_from_scratch.py +++ b/tests/install_from_scratch.py @@ -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)