Upgrading

These are the instructions for upgrading Pootle from an older version to a new release.

Warning

When upgrading please ensure that you:

  • Carefully read this page before proceeding
  • Make all the recommended backups
  • Try to follow these instructions as closely as possible

This page is divided in three sections:

  1. Preparatory tasks that should be performed before upgrading.
  2. Detailed steps to actually perform the upgrade.
  3. Suggested tasks to fine tune the setup after upgrading.

Preparatory tasks

Before upgrading Pootle to a newer version, make sure to go through this checklist.

  • Familiarize yourself with important changes in Pootle.
  • If you want to change the database backend then have a look at the database migration page first. We discourage using SQLite, so if you are using it please migrate to a real database server.
  • Ensure that you meet the hardware requirements for the newer version.
  • Always make backups of all your translation files (your whole POOTLE_TRANSLATION_DIRECTORY). Use the sync_stores command to synchronize all your translation files to disk before making any backup.
  • Also backup your settings, to avoid losing any settings customizations.
  • Make a backup of your complete database using the appropriate dump command for your database system. For example mysqldump for MySQL, or pg_dump for PostgreSQL.
  • And don’t forget to backup any code, templates or styling customization that you have done to your installation.
  • Familiarize yourself with any new settings that have been introduced.

Upgrading

Upgrading Pootle using the pip.

Note

You will need to adjust these instructions if you installed Pootle using another method, such as directly from a Git checkout.

Warning

Always backup the following before upgrading:

  • the entire database
  • all the settings
  • all your translation files
  • any code customizations
  • any templates customizations
  • any styling customizations

To perform the upgrade follow the next steps:

  • If you want to perform a database migration then do it first.

  • We highly recommended that you use a virtual environment. If your install currently doesn’t use one then please set up a virtualenv.

  • If you are upgrading from a version older than Pootle 2.7.0, then you must first upgrade to Pootle 2.6.0.

    (env) $ pip install --upgrade "Pootle>=2.6,<2.7"
    (env) $ pootle setup
    

    Then continue with the upgrade process.

  • Upgrade the Pootle package:

    (env) $ pip install --upgrade Pootle
    
  • Update your custom Pootle settings to adjust for any changes and to include any new settings. Delete any obsolete settings. Check the available settings as needed.

    Note

    Running pootle check will highlight settings that have been made obsolete or renamed.

    Note

    If you are upgrading from a version of Pootle that uses localsettings.py then you must move your custom settings to a new location in order to ensure that Pootle uses them.

  • Perform the database schema and data upgrade by running:

    (env) $ pootle migrate
    
  • Reapply your custom changes to Pootle code, templates or styling. Read about customization of style sheets and templates to adjust your customizations to the correct locations and approach in the new release.

    Note

    If you have customized the CSS styling or the JavaScript code you will have to run the following commands to update the static assets:

    (env) $ cd $pootle_dir/pootle/static/js/
    (env) $ npm install
    (env) $ npm update
    (env) $ pootle webpack
    (env) $ pootle collectstatic --noinput --clear -i node_modules -i *.jsx
    (env) $ pootle assets build
    

    $pootle_dir is the directory where pip installed Pootle. Its location depends on your settings for pip, but by default it should be ~/.virtualenvs/env/lib/python2.7/site-packages/.

  • Finally, restart your server.

Post-upgrade adjustments

  • Check that you can login as an admin user. If your existing admin user has no email address then you will not be able to login. In order the fix this use createsuperuser to create a new superuser, or to create a temporary superuser to fix your existing one.

    (env) $ pootle createsuperuser
    

After a succesful upgrade you can now consider: