These instructions assume you have git and pip installed. If you don’t have pip installed (you probably do) you can install it with the instructions in the pip docs.
Start by getting the source:
$ git clone git://github.com/mozilla/bedrock.git $ cd bedrock
You need to create a virtual environment for Python libraries. Skip the first instruction if you already have virtualenv installed:
$ pip install virtualenv # installs virtualenv, skip if already have it $ virtualenv -p python2.7 venv # create a virtual env in the folder `venv` $ source venv/bin/activate # activate the virtual env. On Windows, run: venv\Scripts\activate.bat $ pip install -U pip # securely upgrade pip $ pip install -r requirements/test.txt # installs dependencies
If you are on OSX and some of the compiled dependencies fails to compile, try explicitly setting the arch flags and try again:
$ export ARCHFLAGS="-arch i386 -arch x86_64" $ pip install -r requirements/test.txt
If you are on Linux, you will need at least the following packages or their equivalent for your distro:
$ python-dev libxslt-dev
Now configure the application to run locally by creating your local settings environment file:
$ cp .env-dist .env
You shouldn’t need to customize anything in there yet.
Sync the database and all of the external data locally. This gets product-details, security-advisories, credits, release notes, localizations, legal-docs etc:
You may also need to install the Gulp cli globally:
$ npm install -g gulp-cli
Bedrock uses yarn to ensure that Node.js packages that get installed are the exact ones we meant (similar to pip hash checking mode for python). Refer to the yarn documentation for adding or upgrading Node.js dependencies.
Run the tests¶
We’re working on fixing this, but for now you need the localization files for the tests to pass. See the Localization section below for instructions on checking those out.
Now that we have everything installed, let’s make sure all of our tests pass. This will be important during development so that you can easily know when you’ve broken something with a change. You should still have your virtualenv activated, so running the tests is as simple as:
$ py.test lib bedrock
To test a single app, specify the app by name in the command above. e.g.:
$ py.test lib bedrock/firefox
If your local tests run fine, but when you submit a pull-request the tests fail in
CircleCI, it could be due to the
difference in settings between what you have in
and what CircleCI uses:
docker/envfiles/demo.env. You can run tests as close to Circle
as possible by moving your
.env file to another name (e.g.
.env, and running tests again.
Make it run¶
To make the server run, make sure you are inside a virtualenv, and then run the server:
$ ./manage.py runserver
If you are not inside a virtualenv, you can activate it by doing:
$ source venv/bin/activate
If you get the error “NoneType is not iterable”, you didn’t check out the latest product-details. See the above section for that.
Next, in a new terminal tab run gulp to watch for local file changes:
If you have problems with gulp, or you for some reason don’t want to use it you can set:
.env file or otherwise set it in your environment and it will collect media for you as you make changes. The reason that this is not the preferred method is that it is much slower than using gulp.
To make it easier to debug, the development environment does not bundle files. If you want to simulate production assets you can set DEBUG=False in your
.env file and run `` ./manage.py collectstatic`` in the virtual environment.
To view them or update to a more recent version update the submodule:
$ git submodule update --init --recursive
Localization (or L10n) files were fetched by the bootstrap.sh command your ran earlier. If you need to update them or switch to a different repo or branch after changing settings you can run the following command:
$ ./manage.py l10n_update
You can read more details about how to localize content here.
Feature Flipping (aka Switches)¶
Environment variables are used to configure behavior and/or features of select pages on bedrock
via a template helper function called
switch(). It will take whatever name you pass to it
(must be only numbers, letters, and dashes), convert it to uppercase, convert dashes to underscores,
and lookup that name in the environment. For example:
switch('the-dude') would look for the
SWITCH_THE_DUDE. If the value of that variable is any of “on”, “true”, “1”, or
“yes”, then it will be considered “on”, otherwise it will be “off”.
You can also supply a list of locale codes that will be the only ones for which the switch is active.
If the page is viewed in any other locale the switch will always return
False, even in
mode. This list can also include a “Locale Group”, which is all locales with a common prefix
(e.g. “en-US, en-GB, en-ZA” or “zh-CN, zh-TW”). You specify these with just the prefix. So if you
switch('the-dude', ['en', 'de']) in a template, the switch would be active for German and
any English locale the site supports.
You may also use these switches in Python in
views.py files (though not with locale support).
from bedrock.base.waffle import switch def home_view(request): title = 'Staging Home' if switch('staging-site') else 'Prod Home' ...
If the environment variable
DEV is set to a “true” value, then all switches will be considered “on” unless they are
explicitly “off” in the environment.
DEV defaults to “true” in local development and demo servers.
To test switches locally:
DEV=False in your
1. Enable the switch in your
1. Restart your web server.
To configure switches for a demo branch. Follow the configuration instructions here.
To work with/test these experiment switches locally, you must add the switches to your local environment. For example:
# to switch on firstrun-copy-experiment you'd add the following to your ``.env`` file SWITCH_FIRSTRUN_COPY_EXPERIMENT=on
To do the equivalent in one of the bedrock apps see the www-config documentation.
A shortcut for activating virtual envs in zsh or bash is . venv/bin/activate. The dot is the same as source.
There’s a project called virtualenvwrapper that provides a better interface for managing/activating virtual envs, so you can use that if you want. Also if you need help managing various versions of Python on your system, the pyenv project can help.