Pontoon is designed to be deployed on Heroku. To deploy an instance of Pontoon on Heroku, you must first create an app on your Heroku dashboard. The steps below assume you’ve already created an app and have installed the Heroku Toolbelt.

For quick and easy deployment without leaving your web browser, click this button:


Pontoon uses several buildpacks in a specific order. They are (in order):

  1. heroku-buildpack-apt for installing Subversion.
  2. heroku-buildpack-ssh for setting up the SSH keys necessary for committing to version control.
  3. The official heroku/nodejs buildpack for installing Node.js programs for pre-processing frontend assets.
  4. The official heroku/python buildpack as our primary buildpack.

You can set these buildpacks on your app with the following toolbelt commands:

# Note that we use add and --index 1 to append to the top of the list.
heroku buildpacks:set heroku/python
heroku buildpacks:add --index 1 heroku/nodejs
heroku buildpacks:add --index 1
heroku buildpacks:add --index 1

Environment Variables

The following is a list of environment variables you’ll want to set on the app you create:


Alternatively, you can put all variables below in a dotenv text file:

VAR="value 1"
OTHER_VAR="other value"

If you do so, you will only have to give the path of this file to Pontoon through the DOTENV_PATH environment variable:

Optional. Email address for the ADMINS setting.
Optional. Name for the ADMINS setting.
The default value is django, which allows you to log in via accounts created using shell. Set to ‘fxa’ if you want to use ‘Firefox Accounts’ (corresponding FXA_* settings must be set). Set to ‘github’ if you want to use ‘GitHub’ (corresponding GITHUB_* settings must be set). Set to ‘gitlab’ if you want to use ‘GitLab’ (corresponding GITLAB_* settings must be set if required). Set to ‘google’ if you want to use ‘Google’ (corresponding GOOGLE_* settings must be set).
Controls whether asynchronous tasks (mainly used during sync) are sent to Celery or executed immediately and synchronously. Set this to False on production.
Maximum number of tasks a Celery worker process can execute before it’s replaced with a new one. Defaults to 20 tasks.

Disables running ./ collectstatic during the build. Should be set to 1.

Heroku’s Python buildpack has a bug that causes issues when running node binaries during the compile step of the buildpack. To get around this, we run the command in our post-compile step (see bin/post_compile) when the issue doesn’t occur.

Controls DEBUG mode for the site. Should be set to False in production.
Signifies whether this is a development server or not. Should be False in production. Adds some additional django apps that can be helpful during day to day development.
Optional. Enables Bugs tab on team pages, which pulls team data from Specific for Mozilla deployments.
Optional. URL to the page displayed to your users when the application encounters a system error. See Heroku Reference for more information.
Optional. Set your Google Analytics key to use Google Analytics.
Optional. Set your Google Cloud Translation API key to use machine translation by Google.
Optional. URL to the page displayed to your users when the application is placed in the maintenance state. See Heroku Reference for more information.
Optional. Enable Sync button in project Admin.
Optional. Set your Microsoft Translator API key to use machine translation by Microsoft.
Optional. API key for accessing the New Relic REST API. Used to mark deploys on New Relic.
Optional. Name to give to this app on New Relic. Required if you’re using New Relic.
Optional. A list of project manager email addresses to send project requests to
Required. Secret key used for sessions, cryptographic signing, etc.
Controls the base URL for the site, including the protocol and port. Defaults to http://localhost:8000, should always be set in production.

Contents of the ~/.ssh/config file used when Pontoon connects to VCS servers via SSH. Used for disabling strict key checking and setting the default user for SSH. For example:


User [email protected]

User [email protected]
SSH private key to use for authentication when Pontoon connects to VCS servers via SSH.


Changing the SSH_CONFIG or SSH_KEY environment variables requires a rebuild of the site, as these settings are only used at build time. Simply changing them will not actually update the site until the next build.

The Heroku Repo plugin includes a rebuild command that is handy for triggering builds without making code changes.


Some environment variables, such as the SSH-related ones, may contain newlines. The easiest way to set these is using the heroku command-line tool to pass the contents of an existing file to them:

heroku config:set SSH_KEY="`cat /path/to/key_rsa`"
Optional. Hostname to prepend to static resources paths. Useful for serving static files from a CDN. Example: //
Path to prepend to LD_LIBRARY_PATH when running SVN. This is necessary on Heroku because the Python buildpack alters the path in a way that breaks the built-in SVN command. Set this to /usr/lib/x86_64-linux-gnu/.
Optional. Multiple sync tasks for the same project cannot run concurrently to prevent potential DB and VCS inconsistencies. We store the information about the running task in cache and clear it after the task completes. In case of an error, we might never clear the cache, so we use SYNC_TASK_TIMEOUT as the longest possible period after which the cache is cleared and the subsequent task can run. The value should exceed the longest sync task of the instance. The default value is 3600 seconds (1 hour).
Timezone for the dynos that will run the app. Pontoon operates in UTC, so set this to UTC.


Pontoon is designed to run with the following add-ons enabled:

  • Database: Heroku Postgres
  • Log Management: Papertrail
  • Error Tracking:
  • Email: Sendgrid
  • Scheduled Jobs: Heroku Scheduler
  • Cache: Memcachier
  • RabbitMQ: CloudAMQP

It’s possible to run with the free tiers of all of these add-ons, but it is recommended that, at a minimum, you run the “Standard 0” tier of Postgres.

Cache Add-ons

Pontoon uses django-bmemcached, which expects the following environment variables from the cache add-on:

Semi-colon separated list of memcache server addresses.
Username to use for authentication.
Password to use for authentication.


By default, the environment variables added by Memcachier are prefixed with MEMCACHIER instead of MEMCACHE. You can “attach” the configuration variables with the correct prefix using the addons:attach command:

heroku addons:attach resource_name --as MEMCACHE

Replace resource_name with the name of the resource provided by the cache addon you wish to use, such as memcachier:100. Use the heroku addons command to see a list of resource names that are available.

RabbitMQ Add-ons

Similar to the cache add-ons, Pontoon expects environment variables from the RabbitMQ add-on:

URL for connecting to the RabbitMQ server. This should be in the format for Celery’s BROKER_URL setting.


Again, you must attach the resource for RabbitMQ as RABBITMQ. See the note in the Cache Add-ons section for details.

Scheduled Jobs

While internal Pontoon DB can be used for storing localizable strings, Pontoon specializes in using version control systems for that purpose. If you choose this option as well, you’ll need to run the following scheduled job:

./ sync_projects

It’s recommended to run this job at least once an hour. It commits any string changes in the database to the remote VCS servers associated with each project, and pulls down the latest changes to keep the database in sync.

Provisioning Workers

Pontoon executes scheduled jobs using Celery. These jobs are handled by the worker process type. You’ll need to manually provision workers based on how many projects you plan to support and how complex they are. At a minimum, you’ll want to provision at least one worker dyno:

heroku ps:scale worker=1

Sync Log Retention

You may also optionally run the clear_old_sync_logs management command on a schedule to remove sync logs from the database that are over 90 days old:

./ clear_old_sync_logs

Database Migrations

After deploying Pontoon for the first time, you must run the database migrations. This can be done via the toolbelt:

heroku run ./ migrate

Creating an Admin User

After deploying the site, you can create a superuser account using the createsuperuser management command:

heroku run ./ createsuperuser --user=admin --email=[email protected]

You’ll then be prompted to set a password for your new user.

If you’ve already logged into the site with the email that you want to use, you’ll have to use the Django shell to mark your user account as an admin:

heroku run ./ shell
# Connection and Python info...
>>> from django.contrib.auth.models import User
>>> user = User.objects.get(email='[email protected]')
>>> user.is_staff = True
>>> user.is_superuser = True
>>> exit()

And with that, you’re ready to start Localizing your projects!