In this section we will see how to install and configure Pontoon. The main paths and users involved in the installation are:
pontoonuser: the system user that will run Pontoon.
/opt/pontoon/current: the path where the latest Pontoon version will be installed with all its dependencies self-contained in a virtualenv.
/var/opt/pontoon: the path where the Pontoon’s data will be stored (cloned repositories, SSH keys,…)
/etc/opt/pontoon.env: the path of the Pontoon’s configuration file.
Feel free the change those paths to fit your requirements but be aware that this manual and the sample configurations provided with it assume they are left unchanged.
First we have to create the
pontoon user that will be used to run Pontoon:
useradd -r -m -s /bin/bash -d /var/opt/pontoon pontoon
And we install some system dependencies:
apt install git build-essential python3 python3-dev python3-venv postgresql-server-dev-all
Then we create the
/opt/pontoon folder that we will need for the
installation and go into it:
mkdir /opt/pontoon cd /opt/pontoon
Downloading and Extracting Pontoon¶
Now we can download the latest version of the Pontoon Debian’s releases (you can, of course, use your own builds here). You will find the releases on Github:
To download a release on the server you can use
Once downloaded, we can extract the archive:
tar -xvzf pontoon_XXXX.XX.XX.X.tar.gz
This will extract a folder named
We will now make a symbolic link named
current that points on it in order
to always have
/opt/pontoon/current pointing on the latest Pontoon
ln -s pontoon-XXXX.XX.XX.X/ current
Virtualenv Creation and Activation¶
Now we will create the virtualenv where all Pontoon’s dependencies will be installed.
First we go in the Pontoon’s installation directory:
Then we create the virtualenv:
python3 -m venv __env__
Once the virtualenv created, we should “activate” it to use it. This can be achieved with the following command:
If the virtualenv was successfully activated, your prompt should now be
Later in this manual, you will have to run commands with this virtualenv
activated. You will just have to repeat the
cd /etc/pontoon/current &&
source __env__/bin/activate commands to do achieve this.
If you want to leave the virtualenv, just use the
You will be able to activate it again with the
cd /etc/pontoon/current &&
source __env__/bin/activate commands.
Installing Pontoon’s Dependencies¶
To install the dependencies, you should run the following commands from within the virtualenv (see above).
First we will update pip, the Python’s package manager (with an older pip version, you may have to compile additional dependencies, including C++ and Rust ones, this is not covered by this manual):
pip install --upgrade pip
Then we can install Pontoon’s dependencies with one of those commands, depending on your Python’s version:
pip install -r requirements.txt # Python 3.8 and above pip install -r requirements.py37.txt # Python 3.7
You can run the
python --version command to get your Python version.
Temporary Fix: The “media” Folder¶
Despite a configurable path for the media folder, Pontoon currently stores its
data in a
media/ folder next to its
pontoon/ folder. To avoid having
data in the
/opt directory, we will make a symbolic link to store the data
mkdir /var/opt/pontoon/media chown pontoon:pontoon /var/opt/pontoon/media ln -s /var/opt/pontoon/media /opt/pontoon/current/media chown pontoon:pontoon /opt/pontoon/current/media
This may be fixed in the future. :)
Now that Pontoon is installed, we will configure it.
We made a sample configuration file that is available in the
folder. You can copy it into the
/etc/opt folder with the following
cp /opt/pontoon/current/debian/pontoon.env /etc/opt
To allow Pontoon to run, you will have to configure at least the following settings:
SITE_URL: The base URL for the Pontoon installation. Please note that the use of TLS (HTTPS) is not optional.
SECRET_KEY: A random key that will be used to encrypt cookies. If this key is changed, all session cookies will be invalidated.
Do not copy the example key. Your key MUST REMAIN SECRET!
DATABASE_URL: The URL containing all the information to connect to the database. It is composed as follow:
Git SSH Configuration¶
If you are using Git, you will have to create and configure an SSH key to allow
push to your repositories.
We will proceed with the following steps:
create an SSH key for Pontoon,
configure Pontoon to use it,
create a user for Pontoon on the Git server,
configure its public key,
initiate the first connection between our server and the Git server.
First we can create the Pontoon’s SSH key with the following command:
su pontoon -c "ssh-keygen -N '' -f ~/.ssh/id_rsa"
You should now have two files in
id_rsa: The private SSH key that will be used locally by Git,
id_rsa.pub: The public key you will have to configure on your Git server (Gitlab, Github,…).
To allow Git to use our newly generated key we should uncomment and configure
GIT_SSH_COMMAND setting in the
GIT_SSH_COMMAND="ssh -v -i /var/opt/pontoon/.ssh/id_rsa"
Then you will have to create an user on you Git server (Gitlab, Github,…) and
to add the Pontoon’s public SSH key (
Once the user created and the key added, you should initiate a first SSH connection to the Git server to add it to the known hosts:
su pontoon ssh -i ~/.ssh/id_rsa firstname.lastname@example.org
email@example.com your Git server user and host.
SSH should ask you if you are sure that you want to connect to this server…
Just answer by typing
The authenticity of host 'git.example.org (XXX.XXX.XXX.XXX)' can't be established. ECDSA key fingerprint is SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Are you sure you want to continue connecting (yes/no/[fingerprint])?
If now the server is asking you for a password, that means the public key is not well configured on the user.
You can now leave from the
pontoon using the
There are a lot of other configurations you will want to set. You will find them all in the sample configuration file:
You will also find some information in Pontoon’s manual:
If you are using Mercurial or SVN, please consider contributing this manual.
Populating the Database¶
We can now populate the database with Pontoon’s tables and data.
To populate the database, you should be in the Pontoon’s installation folder
/opt/pontoon/current) and have its virtualenv activated. This can be
achieved with the following commands:
cd /opt/pontoon/current && source __env__/bin/activate
You should also define the
DOTENV_PATH environment variable with the path
to the Pontoon’s configuration:
Once this is done, just run the following command to populate the database:
python manage.py migrate
Creating the Initial Administrator User¶
Now that the database is ready, we can create the first administrator user.
You should be in the Pontoon’s installation folder, with is virtualenv
activated, and you should have the
DOTENV_PATH environment variable
defined like in the previous step.
To create the user, simply run the following command:
python manage.py createsuperuser --user=admin --firstname.lastname@example.org
adminis the name of the user,
email@example.com the email of the user¹.
¹ If you want to use local
django accounts, you can put your real email
If you plan to use an alternative authentication method (