These instructions will guide you through installing Pootle and its requirements in a virtual environment.
If you only want to have a sneak peek of Pootle then the default configuration and the built-in server will suffice. But in case you want to deploy a real world server, installing optional packages, using a real database and a proper web server is highly recommended.
The easiest way to test and install Pootle is by using pip, however, installating it straight from git sources is another viable approach.
Your Pootle installation will need to be flexible enough to handle the translation load. The recommended hardware depends highly on the performance you expect, the number of users you want to support, and the number and size of the files you want to host.
Whatever hardware you have, you will still benefit from performance improvements if you can optimize your system.
Your disk space should always be enough to store your files and your Pootle database, with some extra space available.
To run Pootle you need a computer running:
Or, any other Unix-like system.
Note
Pootle will not run on Windows since it uses RQ, whose workers cannot run on Windows.
Some developers do develop on Windows so these problems can be worked around for some of the development tasks.
Pootle should be able to run on any system that implements fork()
.
Python 2.7 is required. 2.6 won’t work, and 3.x is not supported.
You will also need the following system services for a working Pootle:
These are preferably installed from system packages.
We’ve made some assumptions in these instructions, adjust as needed:
~/dev/pootle
. For a deployment you’d want to
run this from the webserver directory.In order to install Pootle first create a virtual environment. The virtual
environment allows you to install dependencies independent of your system
packages. For this purpose you need to install the virtualenv
package.
Preferably install it from your system packages. Otherwise use pip:
$ pip install virtualenv
Now create a virtual environment on your location of choice by issuing the
virtualenv
command:
$ cd ~/dev/pootle
$ virtualenv env
To activate the virtual environment run the activate script:
$ source env/bin/activate
With an activated virtual environment, Python will look within the virtual environment for Python libraries. Note that the virtual environment name will be prepended to the shell prompt.
Lastly, we want to make sure that we are using the latest version of pip:
(env) $ pip install --upgrade pip
Use pip to install Pootle into the virtualenv:
(env) $ pip install Pootle
This will also fetch and install a minimum set of dependencies.
Note
Most issues encountered when installing the dependencies relate to missing development packages needed to build the 3rd party packages.
For example, lxml needs a C compiler.
lxml also require the development packages of libxml2 and libxslt.
Depending on your system these may be the libxml2-dev
and libxslt-dev
packages.
To verify that everything installed correctly, you should be able to access the pootle command line tool within your environment.
(env) $ pootle --version
Pootle 2.7.0 (Django 1.7.8, Translate Toolkit 1.13.0)
An alternative to installing from a package is to install directly from Git. This is useful if you are developing Pootle or if you want to have a fine control when updating a server.
Checkout and install the Pootle source code:
(env) $ git clone https://github.com/translate/pootle.git
(env) $ cd pootle
(env) $ pip install .
Alternatively, if you want your install to be live use pip install -e
.
. In this case any changes your make in the repository will be
available to Pootle.
Once Pootle has been installed, you will need to initialize a configuration file as follows:
(env) $ pootle init
This writes the configuration file to ~/.pootle/pootle.conf
. You can pass
an alternative path as an argument if required.
Warning
This default configuration is enough to experiment with Pootle. Don’t use this configuration in a production environment.
The initial configuration includes the settings that you’re most likely to change. For further customization, see the full list of available settings.
By default, Pootle will use SQLite as its database, which is good enough for testing purposes.
If you are using SQLite then skip to Populating the Database.
If you want to migrate to a supported database, then read the database migration tutorial.
If you plan to deploy to a production environment then we highly recommend that you use MySQL or PostgreSQL (MySQL has been most heavily tested).
In this section we are creating a database user for Pootle called pootle
with a password of secret
and a Pootle dabatase named pootledb
.
Warning
It is critical that you set the character set, or encoding, to UTF-8 when creating your database. It is most likely that a target language on Pootle will require Unicode to represent the characters. Pootle itself assumes Unicode throughout.
Use the mysql command to create the user and database:
$ mysql -u root -p # You will be asked for the MySQL root password to log in
> CREATE DATABASE pootledb CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
> GRANT ALL PRIVILEGES ON pootledb.* TO pootle@localhost IDENTIFIED BY 'secret';
> FLUSH PRIVILEGES;
Use the psql command to create a user and database:
$ sudo su postgres # On Ubuntu, may be different on your system
postgres@ $ createuser -P pootle # This will ask you to define the users password.
postgres@ $ createdb --encoding='utf-8' --locale=en_US.utf8 --template=template0 --owner=pootle pootledb
Following the database creation, you need to modify the DATABASES
setting appropriately in your custom settings file, ensuring that you are using
the correct ENGINE
setting for your chosen
database backend.
Before you run Pootle for the first time, you need to create the schema for
the database and populate it with initial data. This is done by executing the
migrate
and initdb
management commands:
(env) $ pootle migrate
(env) $ pootle initdb
Pootle needs at least one user with superuser rights which we create with the
createsuperuser
command.
(env) $ pootle createsuperuser
If you are installing Pootle via pip you can skip this step.
In case you are using a git clone, then you must also build the static assets (note you need Node.js and npm for this):
(env) $ cd pootle/static/js
(env) $ npm install
(env) $ cd ../../..
(env) $ make assets
Pootle stores various cached data in a Redis server. You need to install Redis as required for your operating system or distribution.
On Ubuntu this would be as follows:
$ sudo apt-get install redis-server
$ sudo services redis-server start
Statistics counting and various other background processes are managed by RQ. The rqworker
command needs to be run
continuously in the background in order to process the jobs.
(env) $ pootle rqworker
By default Pootle provides a built-in CherryPy server that will be enough for quickly testing the software. To run it, just issue:
(env) $ pootle start
And the server will start listening on port 8000. This can be accessed from your web browser at localhost:8000.
By default the Pootle server runs on port 8000 and you will probably be interested on binding it to the usual port 80. Also, it’s highly recommended to have all the static assets served by a proper web server, and setting up a web proxy is the simplest way to go.
The Running under a Web Server section has further information on setting up a web server that proxyes requests to the application server.
If you want to omit a reverse proxy and rather prefer to use a web server for serving both dynamic and static content, you can also setup such a scenario with Apache and mod_wsgi for example.
If you plan to run Pootle as a system service, you can use whatever software you are familiar with for that purpose. For example Supervisor, Circus or daemontools might fit your needs.
This has been a quickstart for getting you up and running. If you want to continue diving into Pootle, you should first consider making some optimizations to your setup — don’t forget to switch your database backend! After that you should also adjust the application configuration to better suit your specific needs.
For additional scripting and improved management, Pootle also provides a set of management commands to ease the automation of common administration tasks.
You might also want to create a Local Translation Memory.