Skip to main content

Development Setup

Getting Started​

note

👋 Just a heads up - FxA has a lot of moving parts, and there are plenty of areas that may cause headaches when getting set up. If you get stuck feel free to reach out and we'll do our best to help.

Step 1: Install the system dependencies​

tip

Looking for how to manage Yarn dependencies? Click here to learn more.

Select your operating system to install the required dependencies for developing FxA. The instructions are intended to be followed in order.

First, we need to install git via XCode. This will take a few minutes. Type this in your shell:

xcode-select --install

Then install nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Next, use the command line to install the following:

# JQ (via brew, for more install options see: https://stedolan.github.io/jq/download/)
brew install jq

Finally, manually install the following:

Step 2: Set up and run the code​

Make sure you're using a new shell if you just installed all the dependencies above. That will ensure your environment is configured properly before we move on to the rest of the steps:

# Clone the repository
git clone https://github.com/mozilla/fxa.git
cd fxa

# Install some packages
nvm install          # This picks up on the version in .nvmrc and installs the right thing
npm install -g yarn  # This installs yarn for the specific version of node you just installed above
npm install -g nx

# Initialize the L10n repository
./_scripts/l10n/clone.sh

## Install the node dependencies
yarn install

## On first run, generate an openID key
NODE_ENV=dev yarn workspace fxa-auth-server gen-keys

## Start the project!
yarn start
warning

yarn start starts up all required services via PM2. This includes Redis, MySQL, and Memcached. It is recommended that you don't run these services yourself, or occupy any of the server ports (check out our PM2 configs). Doing so may result in errors.

tip

Additional start command options are available to partially start the stack. E.g. yarn start mza to start only required Mozilla Accounts services.

For a full list of these commands, run yarn nps -h.

  1. Once your services have all started up you should now be able to visit FxA locally. Next up you may want to create an account.
tip

FxA should only be accessed locally using the localhost host, and not via 127.0.0.1.

Step 3: Optional Additions​

Do you need a relying party to test with?​

123done is automatically started with yarn start but it won't work until you finish setting it up. Talk to someone on the team for the right value to put in the packages/123done/secrets.json file.

Do you want to test with 3rd party logins (e.g. Apple or Google)?​

Those need some additional configuration. Talk to someone on the team for the right values to put in your packages/fxa-auth-server/config/secrets.json file.

Do you need the payments services up and running?​

Those need additional configuration also. You'll need to talk to someone on the team for the right values to put in your packages/fxa-auth-server/config/secrets.json file.

Troubleshooting​

If the FxA stack has trouble starting after running yarn start, (for example, a process hangs or you don't see a success message similar to "# Stack Started Successfully !") try starting without cache:

NX_SKIP_NX_CACHE=true yarn start

Be sure to check the PM2 logs to see what, if any errors are reported. To do this:

yarn pm2 logs

To get logs from a specific service, add the service name as an argument. For example, to check auth-server logs:

yarn pm2 logs auth

A full log file can also be found at ~/.pm2/pm2.log and for each service, ~/.pm2/logs/.

If a NX - Daemon processes terminated and closed the connect error message appears when attempting to start the stack, you may turn off the nx daemon locally by adding this setting to a .env file in fxa root:

NX_DAEMON=false

If you encounter errors with auth-server's key server on startup (Failed to get response from: localhost:9000/__heartbeat__) , you may need to generate an openID key. You can check to see if it's present at packages/fxa-auth-server/config/key.json. If it's missing, try running:

NODE_ENV=dev yarn workspace fxa-auth-server gen-keys

You might also notice auth-server showing errors related to missing packages/fxa-auth-server/config/secrets.json. This shouldn't be required to run, but if you'd like to resolve the errors, ask a team member for their auth secrets.json file.

Handy commands​

PM2 is used to control services locally. Use the CLI to control and inspect services:

# Start all services
yarn start

# Stop all services
yarn stop

# Display logs for all services
yarn pm2 logs

# Display logs for just the `auth` service
yarn pm2 logs auth

# Restart the `mysql` service
yarn pm2 restart mysql

# Stop the `content` service
yarn pm2 stop content

Check out the PM2 docs for more commands. If you're using VS Code there is also a handy extension for managing PM2 services.

Additionally, be sure to check out the package.json files in both the root and individual packages to see all available commands.

tip

To avoid wasting computer resources while not working on FxA make sure to stop the servers using yarn stop. Once you are back working on FxA just use the yarn start command to bring the servers back up.

Testing​

tip

While it is possible to run the entire code base's test suite, in development you'll likely want to run a specific test or a subset of tests. Please refer to each package's documentation for detailed instructions on how to test its respective code.

Run unit tests on all or some packages​

note

You might need to run yarn start infrastructure to start services before running tests.

From the root directory you may test all or some FxA packages:

# Test only `fxa-shared`
yarn test fxa-shared

# Test `fxa-shared` and `fxa-auth-server`
yarn test fxa-shared fxa-auth-server

# Test all packages
yarn test all

The above commands invoke the same tests that CI uses, and is not necessarily the same as running yarn test in any given package.

Integration Tests​

You may need credentials to pass all tests, e.g. for auth-server or recovery phone tests. Check 1password or ask a teammate!

Make sure the the infrastructure stack has been started and is running: yarn start infrastructure. From the root directory, run integration tests on some or all FxA packages:

# Test only `fxa-auth-server`
nx test-integration fxa-auth-server

# Test `fxa-shared` and `fxa-auth-server`
nx run-many -t test-integration -p fxa-shared fxa-auth-server

# Test `fxa-shared` and `fxa-auth-server` with 5 parallel workers
nx run-many -t test-integration -p fxa-shared fxa-auth-server --parallel=5

# Test all packages
nx run-many -t test-integration

For details and additional commands, try the NX documentation

Functional Playwright Tests​

You can run functional tests that emulate user behavior. This is a good final pass for any change that affects the UI. It can also save lots of time during development, because running the functional test is quite fast. Note that functional tests are not a replacement for unit tests, so use them judiciously.

Make sure the stack has been started and is running (yarn start). From here, there are a few variants:

# Run tests in headless mode
yarn workspace functional-tests test

# Run tests in debug mode allowing step through of each test stage. Note, using the --grep argument
# or adding .only statements to tests cases is a good idea when debugging, since stepping though every
# single tests is not desirable.
yarn workspace functional-tests test --debug --grep=$test_name

# Run tests in debug console mode, allowing browser debugging.
# https://playwright.dev/docs/debug#selectors-in-developer-tools-console
PWDEBUG=console yarn workspace functional-tests test

# Target a specific test
yarn test workspace functional-tests test --grep=$test_name

For more info, see details at https://playwright.dev.

Emulating a CI environment​

It is possible to run various test suites (known as Jobs) acting as CircleCI. This is useful if you're encountering CI-specific failures. Please refer to this documentation.

Contributing​

If you've got FxA all set up and running, congratulations! Those interested in helping to develop Mozilla accounts should check out the Contributing doc.