Private Relay

Private Relay provides generated email addresses to use in place of personal email addresses.

Recipients will still receive emails, but Private Relay keeps their personal email address from being harvested, and then bought, sold, traded, or combined with other data to personally identify, track, and/or target them.

Development

Please refer to our coding standards for code styles, naming conventions and other methodologies.

Requirements

• python 3.7 (we recommend virtualenv)
• PostgreSQL - even if you are using sqlite for development, requirements.txt installs psycopg2 which requires libpq and Python header files. The following should work:
  • On Windows
  • On Ubuntu: sudo apt install postgresql libpq-dev python3-dev
  • On OSX: brew install postgresql libpq
  • On Fedora: sudo dnf install libpq-devel python3-devel
• SES if you want to send real emails
• Node 12.X – Needed for front-end SCSS compiling
  • NPM
  • Gulp to compile SCSS

Install and Run the Site Locally

1. Clone and change to the directory:

   git clone --recurse-submodules https://github.com/mozilla/fx-private-relay.git
   cd fx-private-relay
   

2. Create and activate a virtual environment:

   virtualenv env
   source env/bin/activate
   

3. Install Python and Node requirements:

   pip install -r requirements.txt
   

   npm install
   

4. Copy .env file for decouple config:

   cp .env-dist .env
   

5. Add a SECRET_KEY value to .env:

   SECRET_KEY=secret-key-should-be-different-for-every-install
   

6. Migrate DB:

   python manage.py migrate
   

7. Create superuser:

   python manage.py createsuperuser
   

8. Run it:

   python manage.py runserver
   

Working with translations

Getting the latest translations

We use a git submodule for translated message files. The --recurse-submodules step of installation should bring the message files into your working directory already, but you may want also want to udpate the translations after install. The easiest way to do that is:

• git submodule update --remote

Add/update messages for translation

The privaterelay/locales directory is a git repository like any other, so to make changes to the messages:

1. Make whatever changes you need in privaterelay/locales/en as you work.

2. cd privaterelay/locales/en

3. git branch message-updates-yyyymmdd

4. git push -u origin message-updates-yyyymmdd

You can then open a pull request from the message-updates-yyyymmdd branch to the l10n repo main branch.

Commit translations for release

To commit updates to the app's translations (e.g., before a release), we need to commit this submodule update. So, if the updated translations are ready to be committed into the app, you can git add the submodule just like any other file:

• git add privaterelay/locales

You can then commit and push to set the app repository to the updated version of the translations submodule:

• git push

Recommended: Enable Firefox Accounts authentication

To enable Firefox Accounts authentication on your local server, you can use the "Firefox Private Relay local dev" OAuth app on accounts.stage.mozaws.net.

To do so:

1. Set ADMIN_ENABLED=True in your .env file

2. Shutdown the server if running, and add the admin tables with:

   python manage.py migrate
   

3. Run the server, now with /admin endpoints:

   python manage.py runserver
   

4. Go to the django admin page to change the default site.

5. Change example.com to 127.0.0.1:8000 and click Save.

6. Go to the django-allauth social app admin page, sign in with the superuser account you created above, and add a social app for Firefox Accounts:

Field	Value
Provider	Firefox Accounts
Name	accounts.stage.mozaws.net
Client id	9ebfe2c2f9ea3c58
Secret key	Request this from #fx-private-relay-eng Slack channel
Sites	127.0.0.1:8000 -> Chosen sites

Now you can sign into http://127.0.0.1:8000/ with an FxA.

⚠️ Remember that you'll need to use an account on https://accounts.stage.mozaws.net/, not the production site, accounts.firefox.com.

Optional: Install and run the add-on locally

Note: The add-on is located in a separate repo. See it for additional information on getting started.

The add-on adds Firefox UI to generate and auto-fill email addresses across the web. Running the add-on locally allows it to communicate with your local server (127.0.0.1:8000) instead of the production server (relay.firefox.com).

Optional: Enable Premium Features

To enable the premium Relay features, we integrate with the FXA Subscription Platform. At a high level, to set up Relay premium subscription, we:

1. Enable Firefox Accounts Authentication as described above.

2. Create a product & price in our Stripe dashboard. (Ask in #subscription-platform Slack channel to get access to our Stripe dashboard.)

3. Link free users of Relay to the appropriate SubPlat purchase flow.

4. Check users' FXA profile json for a subscriptions field to see if they can access a premium, subscription-only feature.

In detail:

1. Enable Firefox Accounts Authentication as described above.

2. Go to our Stripe dashboard. (Ask in #subscription-platform Slack channel to get access to our Stripe dashboard.)

3. Create a new product in Stripe.

4. Add all required product: metadata.

   • Note: each piece of this metadata must have a product: prefix. So, for example, webIconURL must be entered as product:webIconURL.

5. Add capabilities: metadata.

   • Note: Each piece of this metadata must have a format like capabilities:<fxa oauth client ID>, and the value is a free-form string to describe the "capability" that purchasing the subscription gives to the user. E.g., capabilities:9ebfe2c2f9ea3c58 with value of premium-relay.

6. Set some env vars with values from the above steps:

Var	Value
FXA_SUBSCRIPTIONS_URL	https://accounts.stage.mozaws.net/subscriptions
PREMIUM_PROD_ID	prod_IyCWnXUbkYjDgL (from Stripe)
PREMIUM_PRICE_ID	price_1IMG7KKb9q6OnNsL15Hsn1HE (from Stripe)
SUBSCRIPTIONS_WITH_UNLIMITED	"premium-relay" (match the capabilities value you used in Stripe)

Test Premium

There is a comprehensive doc of test cases for purchasing premium Relay.

You can use Stripe's test credit card details for payment.

Production Environments

Requirements

In addition to the requirements for dev, production environments should use:

• PostgreSQL-compatible DB

Environment Variables

Production environments should also set some additional environment variables:

DATABASE_URL=postgresql://<username>:<password>@<host>:<port>/<database>
DJANGO_SECURE_HSTS_SECONDS=15768000
DJANGO_SECURE_SSL_REDIRECT=True