Build Status

Table of contents


Setup your Dev Environment with Docker

When it's done, run docker-compose up, wait for the static files to be built, and go to When you want to stop, do ^C to shut down your containers. If they don't stop properly, run docker-compose down. If you want a new dev environment, stop your containers and run inv new_env.

It's possible to connect your IDE to the python virtual env available inside the backend container (tested with pycharm and vscode). If you run into issues, ping patjouk on slack.

To run commands with Docker, run docker-compose run [SERVICE] [COMMAND]. For example, running the python tests is done by docker-compose run backend ./dockerpythonvenv/bin/python test --settings=donate.settings_test. Since it's pretty long, most cases are covered by Invoke commands.

More information on how to use Docker for local dev is available in the Local dev documentation.


Django Configurations is used for application configuration. The following Configuration Classes are provided:

Value Purpose
Development Base configuration, suitable for local development.
Staging Staging configuration.
Production Production configuration.
ReviewApp Review App configuration. Use this configuration for Heroku Review apps.
ThunderbirdDevelopment Base configuration that enables all the Thunderbird template and string overrides. Suitable for local development.
ThunderbirdStaging Staging configuration for Thunderbird donation configurations.
ThunderbirdProduction Production configuration for Thunderbird donation configurations.
ThunderbirdReviewApp Review App configuration for Thunderbird donation configurations.

Braintree configuration

The following environment variables are required to configure payment processing via Braintree:

Webhook Configuration

There's a webhook endpoint for processing Braintree events. The events it supports are:

The endpoint accepts requests on /braintree/webhook/ and will verify the payload signature to ensure it's a legitimate event. Documentation for Braintree webhooks can be found here.


Basket is a tool run by MoCo to manage newsletter subscriptions and donations. It's listening for messages (JSON) sent to a SQS queue.

Basket donations queue:

Basket has 4 event types we can use:

For this project, we're only using the donation event type.

Donation event type

Example of a donation message sent to Basket, via SQS:

    'data': {
        'event_type': 'donation',
        'last_name': 'alex',
        'email': '',
        'donation_amount': 50,
        'currency': 'usd',
        'created': 1563801762,
        'recurring': false,
        'service': 'paypal',
        'transaction_id': 'ch_1Ez1TSG8Mmx3htnxyShib70n',
        'project': 'mozillafoundation',
        'last_4': '4242',
        'donation_url': 'http://localhost:3000/en-US/',
        'locale': 'en-US',
        'conversion_amount': 50,
        'net_amount': 48.6,
        'transaction_fee': 1.4

Newsletter signup

We're using Basket newsletter HTTP API to signup people to our newsletter. Specs are available in Basket's documentation. (Note that this is different than the SQS approach used for donation events)

Example from

 { format: 'html',
   lang: 'en-US',
   newsletters: 'mozilla-foundation',
   trigger_welcome: 'N',
   source_url: '',
   email: '',
   country: undefined }

Notes: We want to keep the trigger_welcome at N and the format to html. We don't have the country info for now, but from what I understood, it's something we want to change.

Review App

Environment variables

Non-secret envs can be added to the app.json file. Secrets must be set on Heroku in the Review Apps section of the pipelines' settings tab.

Review App for PRs

Opening a PR will automatically create a Review App in the donate-wagtail and thunderbird-donate pipelines. A slack bot posts credentials and links to Review Apps in to the mofo-ra-donate-wagtail and mofo-ra-thunderbird-donate-wagtail channels.

Note: This only work for Mo-Fo staff: you will need to manually open a Review App on Heroku for PRs opened by external contributors.

Review App for branches

You can manually create a review app for any branch pushed to this repo. It's useful if you want to test your code on Heroku without opening a PR yet. To create one:

The review app slack bot will post a message in either the mofo-ra-donate-wagtail or mofo-ra-thunderbird-donate-wagtail with links and credentials as soon as the review app is ready.

SSO and admin logins for local development

The default for admin login for local development is the standard Django login. To use Mozilla SSO via OpenID Connect, set the USE_CONVENTIONAL_AUTH environment variable to False.

To make sure you can log in using your Mozilla SSO credentials, your will need to create a Django superuser with your mozilla email address, using:

docker-compose exec app python createsuperuser

Adding users to the system

The security model currently requires that an existing admin creates an account for a new user first, tied to that user's Mozilla email account, before that user can can log in using SSO.

Further more, in order for SSO authentication to succeed, their account must be a member of the donate user group. To request that an account be added to this group, please file an SSO request bug, making sure to also cc a donate admin in the bug.


Translation is happening on Pontoon, in multiple projects where you can participate:

Project on Pontoon Source repository
Mozilla & Thunderbird UI strings (Django) Repository on GitHub
Mozilla (CMS content) Repository on GitHub
Thunderbird (CMS content) Repository on GitHub

The latest UI source strings are regularly exposed to Pontoon by a Localization PM using the process below. The CMS strings are automatically synchronized with the repositories.

Initial setup:

Exposing latest source strings:

Getting the latest translations for local dev

Latest translations are uploaded to S3. To get them, run:

You don't need to run compilemessages.

The translations_github_commit_[...] file from the archive is only used for debug purposes on Heroku. It can be safely deleted if needed.