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):
- heroku-buildpack-submodules to fetch all related git submodules.
- heroku-buildpack-apt for installing Subversion.
- heroku-buildpack-ssh for setting up the SSH keys necessary for committing to version control.
- The official
heroku/nodejs
buildpack for installing Node.js programs for pre-processing frontend assets. - 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
heroku buildpacks:add --index 1 https://github.com/dmathieu/heroku-buildpack-submodules#b37ffe4361bb9c975dd8e93068c9d296365d748c
The following is a list of environment variables you'll want to set on the app you create:
ADMIN_EMAIL
Optional. Email address for the
ADMINS
setting.ADMIN_NAME
Optional. Name for the
ADMINS
setting.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.
DISABLE_COLLECTSTATIC
Disables running
./manage.py collectstatic
during the build. Should be set to1
.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.
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.
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.
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
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.
STATIC_HOST
Optional. Hostname to prepend to static resources paths. Useful for serving static files from a CDN. Example:
//asdf.cloudfront.net
.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/
.
Note
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`"
TZ
Timezone for the dynos that will run the app. Pontoon operates in UTC, so set this to
UTC
.
Pontoon executes asynchronous 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
Pontoon is designed to run with the following add-ons enabled:
- Database: Heroku Postgres
- Performance Monitoring: New Relic APM
- Log Management: Papertrail
- Error Tracking: Raygun.io
- Email: Sendgrid
- Scheduled Jobs: Heroku Scheduler
- Cache: Memcached Cloud
- 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.
Pontoon uses django-pylibmc, which expects the following environment variables from the cache add-on:
MEMCACHE_SERVERS
Semi-colon separated list of memcache server addresses.
MEMCACHE_USERNAME
Username to use for authentication.
MEMCACHE_PASSWORD
Password to use for authentication.
Note
By default, the environment variables added by Memcached Cloud are prefixed with MEMCACHEDCLOUD
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 memcachedcloud:30
. Use the heroku addons
command to see a list of resource names that are available.
Similar to the cache add-ons, Pontoon expects environment variables from the RabbitMQ add-on:
RABBITMQ_URL
URL for connecting to the RabbitMQ server. This should be in the format for Celery's BROKER_URL setting.
Note
Again, you must attach the resource for RabbitMQ as RABBITMQ
. See the note in the Cache Add-ons section for details.
Pontoon requires a single scheduled job that runs the following command:
./manage.py sync_projects
It's recommended to run this job 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.
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:
./manage.py clear_old_sync_logs
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
After deploying the site, you can create a superuser account using the createsuperuser
management command:
heroku run ./manage.py createsuperuser --noinput --user=admin --email=your@email.com
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()
Changing the
SSH_KEY
orSSH_CONFIG
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.