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.

  1. Manually install the system dependencies.

  2. Clone this repository:

    git clone https://github.com/mozilla/fxa.git

  3. Enter the directory, install Yarn dependencies, and start everything up:

    cd fxa
    yarn install
    yarn start
    caution

    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.

  4. 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.

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.

Troubleshooting​

  • [TODO common issues]

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.

Node.js can be installed in a few ways (including using the installer). The following commands install the latest version, but you should check out .nvmrc to see the specific version FxA expects (YMMV using versions greater than it):

# via nvm (recommended) - https://github.com/nvm-sh/nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node

# via Bash
curl "https://nodejs.org/dist/latest/node-${VERSION:-$(wget -qO- https://nodejs.org/dist/latest/ | sed -nE 's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" > "$HOME/Downloads/node-latest.pkg" && sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"

# via Brew
brew install node

Next, use the command line to install the following:

# Git (via XCode)
xcode-select --install

# Python deps
sudo easy_install pip && sudo pip install virtualenv

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain nightly --profile default

# Yarn (via NPM)
npm install -g yarn

Finally, manually install the following:

Secrets​

When developing locally you may need to set up some secrets in order to effectively work with certain services. These secrets are managed at the package level.

Check out the Secrets section in the following package documentation:

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.

Test 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.

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 Firefox Accounts should check out the Contributing doc.