Developer Setup

The following describes how to set up an instance of the site on your computer for development.

Prerequisites

This guide assumes you have already installed and set up the following:

  1. Git
  2. Python 3.6, pip 8 or higher, and virtualenv
  3. Node.js 8 and NPM 5.
  4. Postgres 9.4
  5. openssl

These docs assume a Unix-like operating system, although the site should, in theory, run on Windows as well. All the example commands given below are intended to be run in a terminal.

Installation

  1. Clone this repository or your fork:

    git clone https://github.com/mozilla/normandy.git
    cd normandy
    
  2. Create a virtualenv for Normandy and activate it:

    virtualenv venv
    source ./venv/bin/activate
    

    Note

    Whenever you want to work on Normandy in a new terminal you’ll have to re-activate the virtualenv. Read the virtualenv documentation to learn more about how virtualenv works.

  3. Install the dependencies using pip:

    pip install -r requirements/default.txt
    

    See also

    Errors during pip install

    How to troubleshoot errors during pip install.

  4. Install frontend dependencies using yarn and build the frontend code using npm:

    yarn install
    npm run build
    
  1. Create a Postgres database for Normandy. By default it is assumed to be named normandy:

    createdb normandy
    

    Note

    By default, it will connect to localhost using the global postgres user. If you use a different name for the database, or otherwise want to customize how you connect to the database, you may specify the database URL by adding the following to a .env file at the root of the repo:

    DATABASE_URL=postgres://username:password@server_addr/database_name
    
  2. Initialize your database by running the migrations:

    python manage.py migrate
    
  3. Create a new superuser account:

    python manage.py createsuperuser
    
  4. Pull the latest geolocation database using the download_geolite2.sh script:

    ./bin/download_geolite2.sh
    
  5. Load actions into the database:

    python manage.py update_actions
    
  6. Update product details:

python manage.py update_product_details
  1. Load in initial data:
python manage.py initial_data

Once you’ve finished these steps, you should be able to start the site by running:

./bin/runsslserver.sh

Note

The runsslserver.sh command automatically creates a self-signed certificate in the etc/ssl directory of the repository. When viewing the site for the first time, you will have to create a certificate exception to allow Firefox to accept the certificate and access the site over HTTPS.

The site should be available at https://localhost:8000/.

Autograph

If you want to execute recipes on your local instance using the recipe client, you’ll need to set up Autograph to sign recipes as you save them:

  1. Follow the Autograph installation instructions to launch a development instance of Autograph.

  2. Add the following configuration to .env (create the file if it does not exist yet):

    DJANGO_AUTOGRAPH_URL=http://localhost:8765/
    DJANGO_AUTOGRAPH_HAWK_ID=normandev
    DJANGO_AUTOGRAPH_HAWK_SECRET_KEY=3dhoaupudifjjvm7xznd9bn73159xn3xwr77b61kzdjwzzsjts
    

With the configuration in place, you should see log messages when saving recipes that look like this:

INFO 2017-05-01 19:58:04,274 normandy.recipes.models Requesting signatures for recipes with ids [16] from Autograph
INFO 2017-05-01 19:58:04,301 normandy.recipes.utils Got 1 signatures from Autograph

Therapist

If you want to automatically enforce Normandy code style guidelines, you can use the Therapist pre-commit hook. To install Therapist, simply run:

pip install therapist

After that, you should be able to run the following to set up the git pre-commit hook:

therapist install

After that, whenever you make a new commit Therapist will check the changed code. This will save time when submitting pull requests.

If you want Therapist to attempt to automatically fix linting issues you can install the hook using:

therapist install --fix

If you ever need to bypass Therapist, you can do so by passing --no-verify to your git commit command.