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.
Please refer to our coding standards for code styles, naming conventions and other methodologies.
- python 3.10 (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
- Volta – Sets up the right versions of Node and npm, needed to compile the front-end
-
Clone and change to the directory:
git clone --recurse-submodules https://github.com/mozilla/fx-private-relay.git cd fx-private-relay
-
Create and activate a virtual environment:
Unix based systems:
virtualenv env source env/bin/activate
Windows:
python -m venv env source env/Scripts/activate
-
Install Python and Node requirements:
pip install -r requirements.txt
cd frontend npm install cd ../
Note: If you're running on Windows, you may run into an issue with usage of environment variables in npm scripts. You can force npm to use git-bash:
npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"
. This the default location, your install may be different. -
Copy
.env
file fordecouple
config:cp .env-dist .env
-
Add a
SECRET_KEY
value to.env
:SECRET_KEY=secret-key-should-be-different-for-every-install
-
Migrate DB:
python manage.py migrate
-
Create superuser:
python manage.py createsuperuser
-
Run the backend:
python manage.py runserver
and in a different terminal, build the frontend:
cd frontend npm run watch
The following docs will get you started with development, include creating new strings to translate. See Translation and Localization for general information on Relay localization.
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 update the translations after install. The easiest way to do
that is:
git submodule update --remote
To update the submodule automatically when running git pull
or other commands:
git config --global submodule.recurse true
The privaterelay/locales
directory is a git repository like any other, so to
make changes to the messages:
-
Make whatever changes you need in
privaterelay/locales/en
as you work. -
cd privaterelay/locales/en
-
git branch message-updates-yyyymmdd
-
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.
If you're not yet ready to submit some strings for translation, you can
tentatively add them to frontend/pendingTranslations.ftl
. Strings in that file
will show up until strings with the same ID are added to the l10n repository.
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
An automated process updates the submodule daily, bringing in any new changes and translations from the Localization Team.
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:
-
Set
ADMIN_ENABLED=True
in your.env
file -
Shutdown the server if running, and add the admin tables with:
python manage.py migrate
-
Run the server, now with
/admin
endpoints:python manage.py runserver
-
Change
example.com
to127.0.0.1:8000
and click Save. -
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.
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
).
npm run watch
watches the frontend/src
directory and builds the frontend
when it detects changes. However, creating a production build is just time-consuming
enough to interrupt your development flow. It is therefore also possible to run the
front-end on a separate server that only recompiles changed modules, and does not
apply production optimizations. To do so, instead of npm run watch
, run
npm run dev
.
The frontend is now available at http://localhost:3000. Keep in mind that this
does make your local development environment less similar to production; in
particular, authentication is normally bound to the backend server, and thus
needs to be simulated when running the frontend on a separate server. If
you make any changes related to authentication, make sure to test them using
npm run watch
as well.
Note: Premium features are automatically enabled for any user with an email address ending in
mozilla.com
, getpocket.com
, or mozillafoundation.org
(see PREMIUM_DOMAINS
in
emails/models.py
). To mimic the customer's experience, it is recommended to follow the below
procedure.
To enable the premium Relay features, we integrate with the FXA Subscription Platform. At a high level, to set up Relay premium subscription, we:
-
Enable Firefox Accounts Authentication as described above.
-
Create a product & price in our Stripe dashboard. (Ask in #subscription-platform Slack channel to get access to our Stripe dashboard.)
-
Link free users of Relay to the appropriate SubPlat purchase flow.
-
Check users' FXA profile json for a
subscriptions
field to see if they can access a premium, subscription-only feature.
In detail:
-
Enable Firefox Accounts Authentication as described above.
-
Go to our Stripe dashboard. (Ask in #subscription-platform Slack channel to get access to our Stripe dashboard.)
-
Create a new product in Stripe.
-
Add all required
product:
metadata.- Note: each piece of this metadata must have a
product:
prefix. So, for example,webIconURL
must be entered asproduct:webIconURL
.
- Note: each piece of this metadata must have a
-
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 ofpremium-relay
.
- Note: Each piece of this metadata must have a format like
-
Set some env vars with values from the above steps:
Var | Value |
---|---|
FXA_SUBSCRIPTIONS_URL |
https://accounts.stage.mozaws.net/subscriptions |
PERIODICAL_PREMIUM_PROD_ID |
prod_KEq0LXqs7vysQT (from Stripe) |
PREMIUM_PLAN_ID_US_MONTHLY |
price_1LiMjeKb9q6OnNsLzwixHuRz (from Stripe) |
PREMIUM_PLAN_ID_US_YEARLY |
price_1LiMlBKb9q6OnNsL7tvrtI7y (from Stripe) |
PHONE_PROD_ID |
prod_LviM2I0paxH1DZ (from Stripe) |
PHONE_PLAN_ID_US_MONTHLY |
price_1LDqw3Kb9q6OnNsL6XIDst28 (from Stripe) |
PHONE_PLAN_ID_US_YEARLY |
price_1Lhd35Kb9q6OnNsL9bAxjUGq (from Stripe) |
BUNDLE_PROD_ID |
prod_MQ9Zf1cyI81XS2 (from Stripe) |
BUNDLE_PLAN_ID_US |
price_1Lwp7uKb9q6OnNsLQYzpzUs5 (from Stripe) |
SUBSCRIPTIONS_WITH_UNLIMITED |
"premium-relay" (match the capabilities value you used in Stripe) |
SUBSCRIPTIONS_WITH_PHONE |
"relay-phones" (match the capabilities value you used in Stripe) |
In frontend/
, set ANALYZE=true
when running npm run build
to generate a
report detailing which modules are taking up most of the bundle size. A report
will be generated for both the client and server part of the frontend, but since
we only use the client, we're really only interested in that. The reports will
automatically open in your browser, and can also be found in
/frontend/.next/analyze/
.
ANALYZE=true npm run build
There is a comprehensive doc of test cases for purchasing premium Relay.
You can use Stripe's test credit card details for payment.
In addition to the requirements for dev, production environments should use:
- PostgreSQL-compatible DB
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