Installing Olympia the long way¶

Note

The following documentation is deprecated. The approved installation is via Docker.

The following instructions walk you through installing and configuring all required services from scratch.

We’re going to use all the hottest tools to set up a nice environment. Skip steps at your own peril. Here we go!

Requirements¶

To get started, you’ll need:

Python 2.7 (2.7 -> 2.7.10)
Node 0.10.x or higher
MySQL
ElasticSearch
libxml2 (for building lxml, used in tests)

OS X and Ubuntu instructions follow.

There are a lot of advanced dependencies we’re going to skip for a fast start. They have their own section.

If you’re on a Linux distro that splits all its packages into -dev and normal stuff, make sure you’re getting all those -dev packages.

On Ubuntu¶

The following command will install the required development files on Ubuntu or, if you’re running a recent version, you can install them automatically:

sudo apt-get install python-dev python-virtualenv libxml2-dev libxslt1-dev libmysqlclient-dev memcached libssl-dev swig openssl curl libjpeg-dev zlib1g-dev libsasl2-dev nodejs nodejs-legacy

Note

As of writing, M2Crypto is only compatible with swig <=3.0.4 version’s. So, if you encounter a libssl exception while running make full_init, you might have to downgrade swig to version <=3.0.4.

On OS X¶

The best solution for installing UNIX tools on OS X is Homebrew.

The following packages will get you set for olympia:

brew install python libxml2 mysql libmemcached openssl swig jpeg

Note

As of writing, M2Crypto is only compatible with swig <=3.0.4 version’s. So, if you encounter a libssl exception while running make full_init, you might have to downgrade swig to version <=3.0.4.

MySQL¶

You’ll probably need to configure MySQL after install (especially on Mac OS X) according to advanced installation.

See Database for creating and managing the database.

Elasticsearch¶

You’ll need an Elasticsearch server up and running during the init script. See Elasticsearch for more instructions.

Use the Source¶

Grab olympia from github with:

git clone https://github.com/mozilla/olympia.git
cd olympia

olympia.git is all the source code. Updating is detailed later on.

virtualenv and virtualenvwrapper¶

virtualenv is a tool to create isolated Python environments. This will let you put all of Olympia’s dependencies in a single directory rather than your global Python directory. For ultimate convenience, we’ll also use virtualenvwrapper which adds commands to your shell.

Are you ready to bootstrap virtualenv and virtualenvwrapper? Since each shell setup is different, you can install everything you need and configure your shell using the virtualenv-burrito. Type this:

curl -sL https://raw.github.com/brainsik/virtualenv-burrito/master/virtualenv-burrito.sh | $SHELL

Open a new shell to test it out. You should have the workon and mkvirtualenv commands.

virtualenvwrapper Hooks (optional)¶

virtualenvwrapper lets you run hooks when creating, activating, and deleting virtual environments. These hooks can change settings, the shell environment, or anything else you want to do from a shell script. For complete hook documentation, see http://www.doughellmann.com/docs/virtualenvwrapper/hooks.html.

You can find some lovely hooks to get started at http://gist.github.com/536998. The hook files should go in $WORKON_HOME ($HOME/Envs from above), and premkvirtualenv should be made executable.

Getting Packages¶

Now we’re ready to go, so create an environment for olympia:

mkvirtualenv olympia

That creates a clean environment named olympia using your default python. You can get out of the environment by restarting your shell or calling deactivate.

To get back into the olympia environment later, type:

workon olympia  # requires virtualenvwrapper

Note

Olympia requires Python 2.7.

Note

If you want to use a different Python binary, pass the name (if it is on your path) or the full path to mkvirtualenv with --python:

mkvirtualenv --python=/usr/local/bin/python2.7 olympia

Finish the install¶

First make sure you have a recent pip for security reasons:

pip install --upgrade pip

From inside your activated virtualenv, install the required python packages, initialize the database, create a super user, compress the assets, …:

make full_init

Settings¶

Most of olympia is already configured in settings.py, but there’s some things you may want to configure locally. All your local settings go into local_settings.py. The settings template for developers, included below, is at docs/settings/local_settings.dev.py.

from settings import *  # noqa

INTERNAL_IPS = ('127.0.0.1', )

I’m extending INSTALLED_APPS and MIDDLEWARE_CLASSES to include the Django Debug Toolbar. It’s awesome, you want it.

The file local_settings.py is for local use only; it will be ignored by git.

Database¶

By default, Olympia connects to the olympia database running on localhost as the user root, with no password. To create a database, run:

$ mysql -u root -p
mysql> CREATE DATABASE olympia CHARACTER SET utf8 COLLATE utf8_unicode_ci;

If you want to change settings, you can either add the database settings in your local_settings.py or set the environment variable DATABASE_URL:

export DATABASES_DEFAULT_URL=mysql://<user>:<password>@<hostname>/<database>

If you’ve changed the user and password information, you need to grant permissions to the new user:

$ mysql -u root -p
mysql> GRANT ALL ON olympia.* TO <YOUR_USER>@localhost IDENTIFIED BY '<YOUR_PASSWORD>';

Finally, to run the test suite, you’ll need to add an extra grant in MySQL for your database user:

$ mysql -u root -p
mysql> GRANT ALL ON test_olympia.* TO <YOUR_USER>@localhost IDENTIFIED BY '<YOUR_PASSWORD>';

Warning

Don’t forget to change <YOUR_USER> and <YOUR_PASSWORD> to your actual database credentials.

The database is initialized automatically using the make full_init command you saw earlier.

Database Migrations¶

Each incremental change we add to the database is done with a versioned SQL (and sometimes Python) file. To keep your local DB fresh and up to date, run migrations like this:

$ schematic migrations/

If, at some point, you want to start from scratch and recreate the database, you can just run the make initialize_db command. This will also fake all the schematic migrations, and allow you to create a superuser.

Run the Server¶

If you’ve gotten the system requirements, downloaded olympia, set up your virtualenv with the compiled packages, and configured your settings and database, you’re good to go.

./manage.py runserver

Note

If you don’t have a LESS compiler already installed, opening http://localhost:8000 in your browser will raise a 500 server error. If you don’t want to run through the Manual installation documentation just right now, you can disable all LESS pre-processing by adding the following line to your local_settings.py file:

LESS_PREPROCESS = False

Be aware, however, that this will make the site VERY slow, as a huge amount of LESS files will be served to your browser on EACH request, and each of those will be compiled on the fly by the LESS javascript compiler.

Create an Admin User¶

To connect to the site, you first need to register a new user “the standard way” by filling in the registration form.

Once this is done, you can either activate this user using the link in the confirmation email sent (it’s displayed in the console, check your server logs), or use the following handy management command:

./manage.py activate_user <email of your user>

If you want to grant yourself admin privileges, pass in the --set-admin option:

./manage.py activate_user --set-admin <email of your user>

Updating¶

To run a full update of olympia (including source files, pip requirements and database migrations):

make full_update

If you want to do it manually, then check the Makefile.

The Contributing page has more on managing branches.

Contact¶

Come talk to us on https://chat.mozilla.org/#/room/#amo:mozilla.org if you have questions, issues, or compliments.

Submitting a Patch¶

See the Contributing page.

Advanced Installation¶

In production we use things like memcached, rabbitmq + celery, elasticsearch, LESS, and Stylus. Learn more about installing these on the Manual installation page.

Note

Although we make an effort to keep advanced items as optional installs you might need to install some components in order to run tests or start up the development server.