Firefox Accounts
The Firefox Accounts (fxa) monorepo
Table of Contents
Getting Started
Contributing
Dependencies
Secrets
Firefox Custom Profile
Functional Tests
Node debugging
Android debugging
FxA Email Service
Firefox for Android
Firefox for iOS
Running with MailDev
Other tasks
Documentation
Getting Started
-
Manually install the system dependencies for OS X or Ubuntu. Note that WSL is required for development work on Windows.
-
Clone this repository.
git clone https://github.com/mozilla/fxa.git
-
Run:
cd fxa yarn install npm start
Note: If yarn install
fails, ensure your yarn -v
is at least 1.22.0
.
Note this starts up all required services, including Redis, MySQL, and Memcached. It is recommended that you don't run these services yourself, or occupy any of the server ports. Doing so may result in errors.
- Visit localhost:3030.
Use the PM2 tool to stop and start the servers, and read server logs.
To start all servers:
npm start
The most common commands are:
-
npm stop
- stop all servers. -
./pm2 status
- display running servers. -
./pm2 logs
- logs for all servers (note: this must be used to verify accounts). -
./pm2 logs auth
- display logs for serviceauth
. -
./pm2 stop content
- stopcontent
service. -
./pm2 restart mysql
- restartmysql
process. -
More commands in the PM2 Readme.
Contributing
See the separate CONTRIBUTING.md to learn how to contribute.
Workflow
This is an example workflow for fxa.
After installing fxa run npm start
. Use ./pm2 status
command to check the status of the servers:
To avoid wasting computer resources while not working on FxA make sure to stop the servers using npm stop
.
Once you are back working on FxA just use the npm start
command to bring the servers back up.
Verifying email and viewing logs
Use the ./pm2 logs
command to get the logs of all servers. You may also use ./pm2 logs [id]
to just see the logs for that particular server.
When you signup for an account using the form on localhost:3030/signup
the "inbox" logs will print out the verification code that you need to copy paste into your browser to verify your account locally:
If you get an error
status for any of the servers please verify that you installed all required dependencies. Otherwise file an issue on this repository or connect with the team on Firefox Accounts Riot.
Managing dependencies
Use yarn
to add dependencies. To add a dependency to a single package, which is what you'll usually want, run something like:
yarn workspace fxa-shared add --dev eslint
For multiple packages use workspaces foreach.
To update dependencies use yarn up or yarn workspace <name> up
.
Dependencies
Required developer dependencies: Git, node.js 12+ with npm 6, Python 2.6+, Java 8+, Rust nightly+, libgmp, graphicsmagick, docker, gcloud CLI > Yarn 2
Brew):
OS X (withXcode and OS X Command Line Tools are required, install it and verify that command line tools installed:
xcode-select --install
then:
sudo easy_install pip && sudo pip install virtualenv
Ubuntu:
sudo apt-get install build-essential git libgmp3-dev graphicsmagick python-virtualenv python-dev pkg-config libssl-dev curl openjdk-11-jre firefox
Follow the Docker CE instructions to install Docker.
Docker commands require sudo, to avoid it, follow steps below:
- Add the docker group if it doesn't already exist
sudo groupadd docker
- Add the connected user $USER to the docker group
sudo gpasswd -a $USER docker
- Restart the docker daemon
sudo service docker restart
Installing Node.js
We currently use Node 12. See https://nodejs.org
Alternatively, the Node Version Manager makes working with different versions of Node easy.
nvm install 12
nvm alias default 12
Installing Java
Java is used to run Selenium functional tests
OS X:
Download from java.com/en/download/
Installing Rust
Rust Nightly is used for the fxa-email-service
Ubuntu and OS X
curl https://sh.rustup.rs -sSf | sh
Once the installer begins:
- Select "2) Customize installation"
- Leave "Default host triple" blank, hit "enter"
- Type "nightly" for "Default toolchain"
- Type "y" for "Modify PATH variable?"
- Select "1) Proceed with installation"
Secrets
When developing locally you may need to set up some secrets in order to effectively work with certain servers. These secrets are managed at the package level.
Check out the Secrets section in the following READMEs:
Testing
Test all or some packages
- You might need to run
yarn start infrastructure
before running tests to start services.
From the root directory you may test all or some FxA packages:
# Test only `fxa-shared`
yarn test fxa-shared
# Test `fxa-auth-db-mysql` and `fxa-auth-server`
yarn test fxa-auth-db-mysql fxa-auth-server
# Test all packages
yarn test all
- Note that this invokes the same test suite that CI uses, and is not necessarily the same as running
yarn test
in any given package.
Emulating CI environment
It is possible to run various test suites (known as Jobs) acting as Circle CI. This is useful if you're encountering CI-specific failures. Please refer to this documentation.
Firefox Custom Profile
Use npm start firefox
to start Firefox with local server configurations.
Available options:
FXA_ENV=local
orlatest
orstable
orstage
(NOTE:local
is default).FXA_E10S=true
- add this flag to turn on E10S. (NOTE:false
by default).FXA_DESKTOP_CONTEXT
-context=
value. (NOTE:fx_desktop_v2
is default).FIREFOX_BIN=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin npm start
FIREFOX_DEBUGGER=true
- open Browser Toolbox on start (NOTE:false
by default for speed).
Node debugging
It's possible to debug a running node process using a variety of debuggers (see the node debugging docs for details).
We have also extensively documented working with the FxA code-base using VS Code.
Debugging a server
npm start
runs some of the services with the debugger enabled by default.
- Start the whole server as usual (
npm install && npm start
from top-level in the monorepo) - To see which debug port each service is listening on check
.vscode/launch.json
or thepm2.config.js
file of the package you're interested in. - Connect to the process to debug it:
- Using Google Chrome, go to
chrome://inspect
, then click the process to connect to devtools.- you may need to add a new target in the "Configure..." menu with the correct debug port
- VSCode requires setting up a
.vscode/launch.json
file; see the VSCode docs for details.
- Using Google Chrome, go to
Default Debug Ports
If you're using npm start
, the following ports are used for --inspect
:
Port | Service |
---|---|
9130 | content-server |
9140 | admin-panel |
9150 | admin-server |
9160 | auth-server |
9170 | payments-server |
9180 | event-broker |
9190 | support-panel |
9200 | graphql-api |
Debugging tests
The node debugger can also be attached to a running test process. Firefox Accounts uses a variety of test frameworks, so the steps vary for the different servers. The --inspect
argument is used in the examples below, but --inspect-brk
can also be used to pause the process as soon as it starts.
mocha tests (fxa-shared)
For mocha, pass the --timeout 0
option, otherwise the test will fail if you step through it and exceed the default timeout (currently 2 seconds on fxa-shared
):
node --inspect ./node_modules/.bin/mocha --timeout 0 path/to/file
In fxa-shared
, this incantation works for some directories, but not yet others.
jest tests (fxa-payments-server)
For jest, pass the --runInBand
argument, so it doesn't fork off the test runner to a separate process that isn't available to the inspector:
node --inspect ./node_modules/.bin/jest --runInBand --config server/jest.config.js filematcher
where filematcher
is a regex that matches against test file paths. If you omit filematcher
, Jest will run all tests (but you have to hit Enter a second time to trigger the test run).
Android debugging
The following technique works with any Android application and can also be used for Firefox for Android.
Simply forward the following ports from the host machine to the Android device:
npm run adb-reverse
or
adb reverse tcp:3030 tcp:3030 # Content server
adb reverse tcp:9000 tcp:9000 # Auth server
adb reverse tcp:9010 tcp:9010 # OAuth server
adb reverse tcp:1111 tcp:1111 # Profile server
adb reverse tcp:5000 tcp:5000 # Sync server
Then run npm start
and get to work!
FxA Email Service
Skip this if you are not working on the fxa-email-service.
The pm2 scripts run the latest
docker version of the email service by default. If you want to
start making changes to the email service then do the following:
- Stop the email-service using
./pm2 stop <email_service_id>
- Build the service:
cd packages/fxa-email-service; cargo build --bin fxa_email_send
- Run the service:
cd packages/fxa-email-service; ./scripts/run_send.sh
Firefox for iOS
Skip this if you are not working on Firefox for iOS and FxA.
You can test sync locally in Firefox iOS using the XCode simulator. Follow the steps at github.com/mozilla/firefox-ios and setup firefox-ios build locally. Currently there is no way to dynamically switch servers in Firefox for iOS, to use local servers you need to run the script below:
FIREFOX_IOS_HOME=<path_to_firefox_ios_project> npm run config-fxios
After the script you need to rebuild firefox-ios.
Running with MailDev
If you want to inspect emails, you can run fxa with MailDev.
Install
npm install maildev -g
Run
npm start
./pm2 stop inbox
Once services have started, you can start MailDev on port 9999. You might have to start MailDev with sudo permissions.
sudo maildev -s 9999
All emails sent can be viewed from http://localhost:1080.
Documentation
The Firefox Ecosystem Platform serves as a documentation hub for Firefox Accounts, Services, Synced Client Integrations, and Subscription Platform.
In addition to the ecosystem docs, each package has it's own README.md and docs/
directory with info specific to that project.
- 123done README
- browserid-verifier README
- fortress README
- fxa-auth-db-mysql README / docs/
- fxa-auth-server README / docs/
- fxa-content-server README / docs/
- fxa-email-event-proxy README
- fxa-email-service README / docs/
- fxa-event-broker README / docs/
- fxa-geodb README
- fxa-js-client README
- fxa-payments-server README
- fxa-profile-server README / docs/
- fxa-shared README
- fxa-support-panel README