Upgrading

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

Stop your running Pootle

Stop your running Pootle while you upgrade to prevent updates to your data during the migration process. If you have RQ workers running stop those also.

Backup your system

Warning

Before upgrading we strongly recommend that you backup your current system.

You must synchronize all your translations to disk:

(env) $ pootle sync_stores

Migrate your database

If you are currently using SQLite for your database you will need to migrate to either MySQL (InnoDB) or PostgreSQL before you upgrade.

Latest changes

Before upgrading Pootle familiarize yourself with important changes since the version that you are upgrading from.

Check Pootle requirements

You should check that you have all of the necessary Pootle requirements and have installed all required system packages.

Warning

Pootle 2.7.0 or newer requires Python 2.7

If you are upgrading from a virtual environment using an earlier Python version, you must upgrade or rebuild your virtual environment first.

Activate virtualenv

These instructions assume that you are using virtualenv and you have activated a virtual environment named env as follows:

$ source env/bin/activate
(env) $

Update pip and setuptools

You should now upgrade pip and setuptools to the latest version:

(env) $ pip install --upgrade pip setuptools

Upgrading from a version older than 2.6

If you are upgrading from a version older than 2.6 you will need to first upgrade to the latest 2.6.x version and then you will be able to upgrade to the latest version.

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

Warning

The 2.6.x releases are meant only as a migration step.

You must upgrade immediately to the latest version once setup has completed.

Clean up stale Python bytecode

You should remove any stale Python bytecode files before upgrading.

Assuming you are in the root of your virtualenv folder you can run:

(env) $ pyclean .

Upgrading from version 2.6.x or later

Upgrade to the latest Pootle version:

(env) $ pip install --pre --process-dependency-links --upgrade Pootle

Update and check your settings

You should now update your custom Pootle settings to add, remove or adjust any settings that have changed. You may want to view the latest available settings.

You can check to see if there are any issues with your configuration settings that need to be resolved:

(env) $ pootle check

Note

If you are upgrading from a version of Pootle that uses localsettings.py then you may want to merge your old custom settings with your settings conf file (default location ~/.pootle/pootle.conf).

Start an RQ Worker

Statistics tracking and various other background processes are managed by RQ. The rqworker command needs to be run continuously in order to process the jobs.

If you have not already done so you should install and start a Redis server.

You can start the worker in the background with the following command:

(env) $ pootle rqworker &

In a production environment you may want to run RQ workers as services.

See here for further information about RQ jobs in Pootle.

Review your database configuration

Review the MySQL or PostgreSQL installation instructions for any changes that you need to make to your database.

If you run MySQL you will almost certainly need to make sure you have Time zone definition files loaded into the database.

Migrate your database schema

Once you have updated your settings you can perform the database schema and data upgrade by running. This is done as follows:

(env) $ pootle migrate --fake-initial

You will also need to update the stats data held in Pootle

(env) $ pootle update_data

Refreshing checks

You must now update the translation checks. You will need to have an RQ worker running to complete this.

(env) $ pootle calculate_checks

This command will dispatch jobs to the RQ worker and may take some time.

If you wish to run calculate_checks in the foreground without using the RQ worker you can use the --no-rq option.

Refreshing scores

If you are upgrading from a version prior to 2.8rc6, you will need to update user scores using refresh_scores.

(env) $ pootle refresh_scores --reset
(env) $ pootle refresh_scores

Drop cached snippets

Redis might have cached HTML snippets referring to outdated static assets. In order for Pootle to return references to the newest assets these cached snippets must go away:

(env) $ pootle flush_cache --django-cache

Set up users

Any accounts that do not have an email address registered will not be able to log in. You can set the email for a user using the update_user_email command.

For example to set the email for user admin to admin@example.com:

(env) $ pootle update_user_email admin admin@example.com

As of Pootle 2.7 users must now verify their email before they can log in.

You can use the verify_user command to bypass email verification for a specific user.

For example to automatically verify the admin user:

(env) $ pootle verify_user admin

If you wish to verify all of your existing users please see the verify_user command for further options.

Check Pootle FS migration

Your projects should have been automatically migrated to use the Pootle FS localfs backend, so you need to check that everything was migrated correctly:

(env) $ pootle fs

This command lists all the available Pootle FS projects. Make sure that all the existing projects in Pootle are listed here.

(env) $ pootle fs state MYPROJECT

This command will show the state of tracked files for a specific project. Run it for each of the projects listed by the previous command.

Ideally we want the state to show no results, i.e. that all files on disk and in Pootle are in sync and are being tracked. If the migration to Pootle FS was not able to fully understand your layout then there may be untracked files.

If there are untracked files you will want do some of these steps:

  1. fs add or fs rm any files that should be tracked but are currently untracked.
  2. Moving and renaming files on the filesystem could resolve missing files.
  3. Adding language mappings could correctly map Filesystem and Pootle stores. This is explained in the Enable translation to a new language instructions.

Next steps

Now that you have Pootle up and running you may want to consider some of the following in order to build a production environment.