1. Design 2. Launch 3. Analyze
Experimenter is a platform for managing experiments in Mozilla Firefox.
https://stage.experimenter.nonprod.dataops.mozgcp.net/
https://experimenter.services.mozilla.com/
- Install docker on your machine
- On linux, setup docker to run as non-root
-
Clone the repo
git clone <your fork>
-
Copy the sample env file
cp .env.sample .env
-
Set DEBUG=True for local development
vi .env
-
Create a new secret key and put it in .env
make secretkey
-
Run tests
make test
-
Setup the database
make refresh
-
Run a dev instance
make up
-
Navigate to it and add an SSL exception to your browser
https://localhost/
One might choose the semi dockerized approach for:
- faster startup/teardown time (not having to rebuild/start/stop containers)
- better ide integration
Notes:
-
Node ^14.0.0 is required
-
Pre reqs (macOs instructions)
brew install postgresql llvm openssl yarn echo 'export PATH="/usr/local/opt/llvm/bin:$PATH"' >> ~/.bash_profile export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/opt/openssl/lib/
-
Install dependencies
source .env poetry install (cd into app) yarn install
-
env values
.env (set at root): DEBUG=True DB_HOST=localhost HOSTNAME=localhost
-
Start postgresql, redis, autograph, kinto
make up_db
-
Django app
# in app poetry shell yarn workspace @experimenter/nimbus-ui build yarn workspace @experimenter/core build ./manage.py runserver 0.0.0.0:7001
Pro-tip: we have had at least one large code refactor. You can ignore specific large commits when blaming by setting the Git config's ignoreRevsFile
to .git-blame-ignore-revs
:
git config blame.ignoreRevsFile .git-blame-ignore-revs
On certain pages an API endpoint is called to receive experiment analysis data from Jetstream to display visualization tables. To see experiment visualization data, you must provide GCP credentials.
- Generate a GCP private key file.
- Ask in #experimenter for the GCP link to create a new key file.
- Add Key > Create New Key > JSON > save this file.
- Do not lose or share this file. It's unique to you and you'll only get it once.
- Rename the file to
google-credentials.json
and place it anywhere inside the/app
directory. - Update your
.env
so thatGOOGLE_APPLICATION_CREDENTIALS
points to this file. If your file is inside the/app
directory it would look like this:GOOGLE_APPLICATION_CREDENTIALS=/app/google-credentials.json
Experimenter uses docker for all development, testing, and deployment.
The following helpful commands have been provided via a Makefile:
Build the application container by executing the build script
Build the supporting services (nginx, postgresql) defined in the compose file
Start a dev server listening on port 80 using the Django runserver
Start postgresql, redis, autograph, kinto on their respective ports to allow running the Django runserver and yarn watchers locally (non containerized)
Start Django runserver, Celery worker, postgresql, redis, autograph, kinto on their respective ports to allow running the yarn watchers locally (non containerized)
Start all containers in the background (not attached to shell)
Run all test and lint suites, this is run in CI on all PRs and deploys
Run python tests
Apply all django migrations
Populates locales and countries
Populates db with dummy experiments
Start a bash shell inside the container (this lets you interact with the containerized filesystem and run Django management commands)
Create dummy SSL certs to use the dev server over a locally secure connection. This helps test client behaviour with a secure connection. This task is run automatically when needed.
Stop and delete all docker containers. WARNING: this will remove your database and all data. Use this to reset your dev environment.
Run kill, migrate, load_locales_countries load_dummy_experiments
Run the integration test suite inside a containerized instance of Firefox. You must also be already running a make up
dev instance in another shell to run the integration tests.
Start a linux VM container with VNC available over vnc://localhost:5900
with password secret
. Right click on the desktop and select Applications > Shell > Bash
and enter tox -c tests/integration/
to run the integration tests and watch them run in a Firefox instance you can watch and interact with.
Experimenter has three front-end UIs right now:
core
is the current UI used for Experimenter intake.nimbus-ui
is a new React UI for an upcoming Experimenter refactor.
Learn more about the organization of these UIs here.
API documentation can be found here
Please see our Contributing Guidelines
Experimenter uses the Mozilla Public License