Permalink
Find file
166 lines (105 sloc) 6.48 KB

Installing Bedrock

Installation

These instructions assume you have git and pip installed. If you don't have pip installed, you can install it with easy_install pip.

Start by getting the source:

$ git clone --recursive git://github.com/mozilla/bedrock.git
$ cd bedrock

(Make sure you use --recursive so that legal-docs are included)

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
$ bin/pipstrap.py                              # 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, etc:

$ bin/sync_all

Lastly, you need to have Node.js and NPM installed. The node dependencies for running the site can be installed with npm:

$ npm install

You may also need to install the Gulp cli globally.

Note

Bedrock uses npm-lockdown to ensure that Node.js packages that get installed are the exact ones we meant (similar to peep.py for python). Refer to the lockdown documentation for adding or upgrading Node.js dependencies.

Run the tests

Important

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

Note

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 .env and what CircleCI uses: .bedrock_demo_env. You can run tests as close to Circle as possible by moving your .env file to another name (e.g. .env-backup), then copying .bedrock_demo_env to .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:

$ gulp

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.

If you have problems with gulp, or you for some reason don't want to use it you can set:

PIPELINE_COLLECTOR_ENABLED=True

in your .env file or otherwise set it in your environment. Then you can run:

$ ./manage.py runserver

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.

Localization

If you want to install localizations, run the following command:

$ ./manage.py l10n_update

You can read more details about how to localize content :ref:`here<l10n>`.

Feature Flipping

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 environment variable 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". If the environment variable DEV is set to one of those "true" values, then all switches will be considered "on" unless they are explicitly "off" in the environment.

Currently, these switches are used to enable/disable Optimizely on many pages of the site. We only add the Optimizely JavaScript snippet to a page when there is an active test to minimize the security risk of the service. We maintain a page on the Mozilla wiki detailing our use of Optimizely and these switches.

To work with/test these Optimizely switches locally, you must add the switches to your local environment. For example:

# to switch on firefox-new-optimizely you'd add the following to your ``.env`` file
SWITCH_FIREFOX_NEW_OPTIMIZELY=True

You then must set an Optimizely project code in .env:

# Optimize.ly project code
OPTIMIZELY_PROJECT_ID=12345

Note

You are not required to set up Optimizely as detailed above. If not configured, bedrock will treat the switches as set to off.

Notes

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.