Deployment¶

Buildpack¶

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 https://github.com/Osmose/heroku-buildpack-ssh.git#v0.1
heroku buildpacks:add --index 1 https://github.com/mozilla/heroku-buildpack-apt.git#v0.1

Environment Variables¶

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

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

DOTENV_PATH=/path/to/my/config.env

ADMIN_EMAIL

Optional. Email address for the ADMINS setting.

ADMIN_NAME

Optional. Name for the ADMINS setting.

AUTHENTICATION_METHOD

The default value is django, which allows you to log in via accounts created using manage.py 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).

CELERY_ALWAYS_EAGER

Controls whether asynchronous tasks (mainly used during sync) are sent to Celery or executed immediately and synchronously. Set this to False on production.

CELERYD_MAX_TASKS_PER_CHILD

Maximum number of tasks a Celery worker process can execute before it’s replaced with a new one. Defaults to 20 tasks.

DEFAULT_FROM_EMAIL

Optional. Default email address to send emails from. Default value: Pontoon <pontoon@hostname>.

DISABLE_COLLECTSTATIC

Disables running ./manage.py 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.

DJANGO_DEBUG

Controls DEBUG mode for the site. Should be set to False in production.

DJANGO_DEV

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.

EMAIL_HOST

SMTP host (default: 'smtp.sendgrid.net')

EMAIL_HOST_PASSWORD

Password for the SMTP connection.

EMAIL_HOST_USER

Username for the SMTP connection (default: 'apikey').

EMAIL_PORT

SMTP port (default: 587)

EMAIL_USE_TLS

Use explicit TLS for the SMTP connection (default: True)

EMAIL_USE_SSL

Use implicit TLS for the SMTP connection (default: False)

ENABLE_BUGS_TAB

Optional. Enables Bugs tab on team pages, which pulls team data from bugzilla.mozilla.org. Specific for Mozilla deployments.

ENABLE_INSIGHTS_TAB

Optional. Enables Insights tab on team pages, which presents data that needs to be collected by the Collect Insights scheduled job. It is advised to run the job at least once before enabling the tab, otherwise the content will be empty. See the spec for more information.

ERROR_PAGE_URL

Optional. URL to the page displayed to your users when the application encounters a system error. See Heroku Reference for more information.

GOOGLE_ANALYTICS_KEY

Optional. Set your Google Analytics key to use Google Analytics.

GOOGLE_TRANSLATE_API_KEY

Optional. Set your Google Cloud Translation API key to use generic machine translation engine by Google.

GOOGLE_AUTOML_PROJECT_ID

Optional. Set your Google Cloud AutoML Translation model ID to use custom machine translation engine by Google.

MAINTENANCE_PAGE_URL

Optional. URL to the page displayed to your users when the application is placed in the maintenance state. See Heroku Reference for more information.

MANUAL_SYNC

Optional. Enable Sync button in project Admin.

MEDIA_ROOT

Optional. The absolute path of the “media” folder the projects will be cloned into (it is located next to the “pontoon” Python module by default).

MICROSOFT_TRANSLATOR_API_KEY

Optional. Set your Microsoft Translator API key to use machine translation by Microsoft.

NEW_RELIC_API_KEY

Optional. API key for accessing the New Relic REST API. Used to mark deploys on New Relic.

NEW_RELIC_APP_NAME

Optional. Name to give to this app on New Relic. Required if you’re using New Relic.

PROJECT_MANAGERS

Optional. A list of project manager email addresses to send project requests to

PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION

Required. Must be set to python. Needed for Google AutoML Translation. Learn more on Protocol Buffers Homepage.

SECRET_KEY

Required. Secret key used for sessions, cryptographic signing, etc.

SITE_URL

Controls the base URL for the site, including the protocol and port. Defaults to http://localhost:8000, should always be set in production.

SSH_CONFIG

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:

StrictHostKeyChecking=no

Host hg.mozilla.org
User pontoon@mozilla.com

Host svn.mozilla.org
User pontoon@mozilla.com

SSH_KEY

SSH private key to use for authentication when Pontoon connects to VCS servers via SSH.

heroku config:set SSH_KEY="`cat /path/to/key_rsa`"

STATIC_HOST

Optional. Hostname to prepend to static resources paths. Useful for serving static files from a CDN. Example: //asdf.cloudfront.net.

SUGGESTION_NOTIFICATIONS_DAY

Optional. Integer representing a day of the week on which the send_suggestion_notifications management command will run. 0 represents Monday, 6 represents Sunday. The default value is 4 (Friday).

SVN_LD_LIBRARY_PATH

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

SYNC_TASK_TIMEOUT

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

SYSTRAN_TRANSLATE_API_KEY

Optional. Set your `SYSTRAN Translate API key`_ to use machine translation by SYSTRAN.

TZ

Timezone for the dynos that will run the app. Pontoon operates in UTC, so set this to UTC.

VCS_SYNC_NAME

Optional. Default committer’s name used when committing translations to version control system.

VCS_SYNC_EMAIL

Optional. Default committer’s email used when committing translations to version control system.

Add-ons¶

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

• Database: Heroku Postgres
• Log Management: Papertrail
• Error Tracking: Raygun.io
• 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.

heroku addons:attach resource_name --as MEMCACHE

Scheduled Jobs¶

Pontoon requires several scheduled jobs to run regularly.

./manage.py sync_projects

./manage.py send_deadline_notifications

./manage.py send_suggestion_notifications

./manage.py send_review_notifications

./manage.py collect_insights

./manage.py clear_old_sync_logs

heroku ps:scale worker=1

Database Migrations¶

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

heroku run ./manage.py migrate

Creating an Admin User¶

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

heroku run ./manage.py createsuperuser --user=admin --email=your@email.com

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 ./manage.py shell
# Connection and Python info...
>>> from django.contrib.auth.models import User
>>> user = User.objects.get(email='your@email.com')
>>> user.is_staff = True
>>> user.is_superuser = True
>>> user.save()
>>> exit()

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