# Installation

These instructions will guide you through installing Pootle and its requirements in a virtual environment.

Pootle installation tutorial (Click to play)

If you only want to have a sneak peek of Pootle then the default configuration and the built-in server will suffice.

Follow the Pootle installation video tutorial, which starts after some basic setup, to see the installation steps in action and expected results.

For a production deployment we strongly recommend that you set up the following:

- Install optional optimization packages
- Use either a MySQL or PostgreSQL database.
- Make use of a front-end web server

Note

Before installing please ensure that you have all the necessary requirements.

Warning

It is important to install Pootle into a virtual environment to ensure the correct packages and permissions. It’s even more important not to install Pootle as the root user on your system. Installing or running Pootle as the root user will expose your system to many potential security vulnerabilities

## Setup assumptions

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

1. All of the Pootle requirements have been installed.
2. We’re installing into `~/dev/pootle`.
3. We’re using SQLite as it’s easy to setup.
4. We’re setting up the essential parts of Pootle including Redis, and RQ Workers.
5. This is a test installation on a single server, and not optimised for production use.
6. We’re installing using pip.

## 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.

Please install virtualenv from your system packages, e.g. on Debian:

    $ sudo apt-get install python-virtualenv

Otherwise you can install virtualenv using pip:

    $ sudo pip install virtualenv

Now create a virtual environment on your location of choice by issuing the virtualenv command:

    $ cd ~/dev/pootle
    $ virtualenv env

Note

for versions of virtualenv prior to 1.10, you may need to call virtualenv with the `--setuptools` option, to ensure the correct environment.

To activate the virtual environment run the activate script:

    $ source env/bin/activate

Once activated 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 and setuptools:

    (env) $ pip install --upgrade pip setuptools

## Installing Pootle

Use pip to install Pootle into the virtual environment:

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

This will also fetch and install Pootle’s dependencies.

Note

pip requires –pre to install pre-release versions of Pootle, i.e. alpha, beta and rc versions. You may require –process-dependency-links if Pootle depends on unreleased versions of third-party software.

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.8.1 (Django 1.10.7, Translate Toolkit 2.2.4)

## Initializing the Configuration

Once Pootle has been installed, you will need to initialize a configuration file:

    (env) $ pootle init

By default the configuration file is saved as `~/.pootle/pootle.conf`. You can pass an alternative path as an argument if required - see the `init` command for all of the options.

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.

## Running 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.

## 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:

Note

You will need to have an RQ worker running to complete this. Alternately, you can use the `--no-rq`.

    (env) $ pootle migrate
    (env) $ pootle initdb

Running `initdb` will take some time as it will create the default projects and stores.

## Creating an admin user

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

    (env) $ pootle createsuperuser

All users are required to verify their email before logging in. If you wish to bypass this step you can use the `verify_user` command.

For example to allow a user named `admin` to log in without having to verify their email address:

    (env) $ pootle verify_user admin

## Running Pootle

The Django default server will be enough for quickly testing the software. To run it, just issue:

    (env) $ pootle runserver --insecure

Warning

There are serious drawbacks to using runserver. Never use it in production.

And the server will start listening on port 8000. Pootle can then be accessed from your web browser at localhost:8000.

## 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.

- Create your first localisation project
- Run Pootle and RQ workers as services
- Set up a reverse-proxy web server for static files
- Use a wsgi server to serve dynamic content
- Check out the available settings
- Check out Pootle management commands
- Optimize your setup
- Set up a Translation Memory Server
- Customize the Pootle UI