Installation

Core developers run Kuma in a Vagrant-managed virtual machine so we can run
the entire MDN stack. (Django, KumaScript, Search, Celery, etc.)
If you're on Mac OS X or Linux and looking for a quick way to get started, you
should try these instructions.

Dependencies

Pure Python Packages

All of the pure Python dependencies are included in the git repository,
in the vendor subdirectory. This allows them to be available on the
Python path without needing to be installed in the system, allowing multiple
versions for multiple projects simultaneously.

Compiled Python Packages

There are a small number of compiled packages, including the MySQL Python
client. You can install these using pip or via a package manager.
To use pip, you only need to do the following.

First SSH into the Vagrant VM:

vagrant ssh

Then disable the virtualenv that is auto-enabled and install the compiled
dependencies:

deactivate
sudo pip install -r requirements/compiled.txt

Configuration

Vagrant

If you'd like to change the way Vagrant works, we've added a few
configuration values that may be worthwhile to look at. In case something
doesn't suffice for your machine, please let us know!

To change the config values, simply create a dotenv file (.env) in the
directory (/home/vagrant/src/.env in the Vagrant VM) and write
<KEY>=<VALUE> for each configuration variable you'd like to set.

Here's the configuration variables that are available for Vagrant:

VAGRANT_NFS

Default: true (Windows: false)
Whether or not to use NFS for the synced folder.

VAGRANT_MEMORY_SIZE

The size of the Virtualbox VM memory in MB. Default: 2048

VAGRANT_CPU_CORES

The number of virtual CPU core the Virtualbox VM should have. Default: 2

VAGRANT_IP

The static IP the Virtualbox VM should be assigned to. Default: 192.168.10.55

Note the two values CHARSET and COLLATION of the TEST setting.
Without these, the test suite will use MySQL's (moronic) defaults when
creating the test database (see below) and lots of tests will fail. Hundreds.

Once you've set up the database, you can generate the schema with Django's
migrate command:

./manage.py migrate

This will generate an empty database, which will get you started!

Assets

If you want to see images and have the pages formatted with CSS you need to
set your settings_local.py with the following:

DEBUG = True
TEMPLATE_DEBUG = DEBUG
SERVE_MEDIA = True

Setting DEBUG = False will put the installation in production mode
and ask for minified assets. In that case, you will need to generate
CSS from stylus and compress resource:

Errors during vagrant up

vagrant up starts the virtual machine. The first time you run
vagrant up it also provisions
the VM - i.e., it automatically installs and configures Kuma software in the
VM. We provision the VM with Ansible roles in the provisioning directory.

Sometimes we put Ansible roles in the wrong order. Which means some
errors can be fixed by simply provisioning the VM again:

vagrant provision

In some rare occasions you might need to run this multiple times. If you find an
error that is fixed by running vagrant provision again, please email us the
error at dev-mdn@lists.mozilla.org and we'll see if we can fix it.

Ubuntu

On Ubuntu, vagrant up might fail after being unable to mount NFS shared
folders. First, make sure you have the nfs-common and nfs-server packages
installed and also note that you can't export anything via NFS inside an
encrypted volume or home dir. On Windows NFS won't be used ever by the way.