# Installation

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.

## Requirements

### Hardware Requirements

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.

### System Requirements

To run Pootle you need a computer running:

- Linux
- Mac OS X

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()`.

### Software requirements

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:

- Redis - all caching and managing of workers uses Redis
- Database - MySQL or PostgreSQL (although for testing SQLite is fine)
- Elasticsearch (optional) - for Local Translation Memory

These are preferably installed from system packages.

## Setup assumptions

We’ve made some assumptions in these instructions, adjust as needed:

1. We’re installing into `~/dev/pootle`. For a deployment you’d want to run this from the webserver directory.
2. We’re using SQLite as its easy to setup. Though we do include instructions for quickly setting up MySQL or PostgreSQL.
3. We’re setting up the key parts of Pootle including Redis, Workers and Local TM.
4. This is a test installation. We’re not setting up a server for hosting or optimising in any way.
5. We’re installing using pip. There are also instructions for setting up Pootle using a git checkout.

## Setting up the virtual environment

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

## Installing Pootle

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)

### Installation from a Git Checkout

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.

## Initializing the Configuration

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.

## Setting Up the Database

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.

### MySQL

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;

### PostgreSQL

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.

## Populating the Database

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

## Creating an admin user

Pootle needs at least one user with superuser rights which we create with the `createsuperuser` command.

    (env) $ pootle createsuperuser

## Static Assets

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

## Background services

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

## Background processes

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

## Running Pootle

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.

## Setting up a Reverse Proxy

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.

## Running Pootle as a Service

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.

## Further Configuration and Tuning

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.