Hacking HOWTO for Contributors¶

Summary ¶

This chapter helps you get a minimal installation of Kitsune up and running to make it easier to contribute.

If you’re setting Kitsune up for deployment, instead of development, make sure you read all the way to the end and then read the additional sections.

If you have any problems getting Kitsune running, let us know. See the Contact us.

Operating systems ¶

Windows ¶

If you’re using Windows as your operating system, you’ll need to set up a virtual machine and run Kitsune in that. Kitsune won’t run in Windows.

If you’ve never set up a virtual machine before, let us know and we can walk you through it. Having said that, it’s not easy to do for people who haven’t done it before.

Mac OSX ¶

Just follow along with the instructions below. Several of us use OSX, so if you run into problems, let us know.

We know these work in Debian, Ubuntu, Arch, and will probably work in other distributions. It’s likely that you’ll encounter some steps that are slightly different. If you run into problems, let us know.

Skip to Testing

Requirements ¶

These are required for the minimum installation:

git
Python 2.7
pip: https://pip.pypa.io/en/latest/
virtualenv
MariaDB 5.5 server and client headers
Memcached Server
libxml and headers
libxslt and headers
libjpeg and headers
zlib and headers
libssl and headers
libffi and headers

These are optional:

Redis
ElasticSearch: Search

Installation for these is very system dependent. Using a package manager, like yum, aptitude, or brew, is encouraged.

memcached ¶

You need to have memcached running. Otherwise CSRF stuff won’t work.

If you are running OSX and using homebrew, you can do something like:

$ brew install memcached

and launch it:

$ memcached

If you are running RedHat/CentOS/Fedora, once you have installed memcached you can start it and configure it to run on startup using:

$ chkconfig memcached on
$ /etc/init.d/memcached start
$ service memcached start

Note

This should probably be somewhere else, but the easy way to flush your cache is something like this:

echo "flush_all" | nc localhost 11211

Assuming you have memcache configured to listen to 11211.

Getting the Source ¶

Grab the source from Github using:

$ git clone https://github.com/mozilla/kitsune.git
$ cd kitsune

Setting up an Environment ¶

It is strongly recommended to run Kitsune in a virtual environment, which is a tool to isolate Python environments from each other and the system. It makes local development much easier, especially when working on multiple projects.

To create a virtual environment:

$ virtualenv venv

which creates a virtualenv named “venv” in your current directory (which should be the root of the git repo. Now activate the virtualenv:

$ source venv/bin/activate

You’ll need to run this command every time you work on Kitsune, in every terminal window you use.

Installing dependencies ¶

Python Packages ¶

All the pure-Python requirements are provided in the requirements directory:

$ pip install -r requirements/default.txt

Additionally, you may install some useful development tools. These are not required, but are helpful:

$ pip install -r requirements/dev.txt

If you intend to run the function UI tests, you will also need to install the appropriate dependencies:

$ pip install -r requirements/test.txt

Node.js Packages ¶

Kitsune relies on some Node.js packages. To get those, you will need to install Node.js and NPM.

Now install the Node.js dependencies with:

$ npm install

This should create a directory named node_modules in your git repo.

Frontend Packages ¶

Kitsune gets libraries and dependencies for client side code from Bower. Bower is installed as a part of the NPM packages in the last step. To install these front-end dependencies run:

$ ./node_modules/.bin/bower install

This will download dependencies into bower_components.

Configuration and Setup ¶

settings_local.py ¶

There is a file called settings_local.py.dist in the kitsune/ directory. This contains a sample set of local settings. Copy the file, name it settings_local.py. and edit it, following the instructions within. Don’t forget to change <YOUR_PASSWORD> to your actual database password.

Note the two settings TEST_CHARSET and TEST_COLLATION. 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.

Additionally, you can copy and modify any settings from kitsune/settings.py into kitsune/settings_local.py and the value will override the default.

Database ¶

You defined a database connection in kitsune/settings_local.py.

Now create the database and grant permissions to the user, based on your database settings. For example, using the settings above:

$ mysql -u root -p
mysql> CREATE DATABASE kitsune CHARACTER SET utf8 COLLATE utf8_unicode_ci;
mysql> GRANT ALL ON kitsune.* TO kitsune@localhost IDENTIFIED BY '<YOUR_PASSWORD>';

To initialize the database, do:

$ ./manage.py migrate

Then we create a superuser to log into kitsune:

./manage.py createsuperuser

You’ll now have an up-to-date database!

After logging in, you can create a profile for the user by going to /users/edit in your browser.

See also the important wiki documents documentation.

Install Sample Data ¶

We include some sample data to get you started. You can install it by running this command:

$ ./manage.py generatedata

Install linting tools ¶

Kitsune uses Yelps Pre-commit for linting. It is installed as a part of the dev dependencies in requirements/dev.txt. To install it as a Git pre-commit hook, run it:

$ venv/bin/pre-commit install

After this, every time you commit, Pre-commit will check your changes for style problems. To run it manually, you can use the command:

$ venv/bin/pre-commit run

which will run the checks for only your changes, or if you want to run the lint checks for all files:

$ venv/bin/pre-commit run --all-files

For more details see the Pre-commit docs.

Product Details Initialization ¶

One of the packages Kitsune uses, product_details, needs to fetch JSON files containing historical Firefox version data and write them within its package directory. To set this up, run this command to do the initial fetch:

$ ./manage.py update_product_details

Pre-compiling JavaScript Templates ¶

We use nunjucks to render Jinja-style templates for front-end use. These templates get updated from time to time and you will need to pre-compile them to ensure that they render correctly. You have two options here:

One time pre-compile (use this if you are not modifying the templates):
```
$ ./manage.py nunjucks_precompile
```
Use gulp to watch for changes and pre-compile (use this if you are making changes to the templates):
```
$ ./node_modules/.bin/gulp watch
```

Testing it out ¶

To start the dev server, run ./manage.py runserver, then open up http://localhost:8000.

If everything’s working, you should see a somewhat empty version of the SUMO home page!

Note

If you see an unstyled site and empty CSS files, you have to remove all empty files having a .less.css since they are empty and should be regenerated.

To do this, run the following command on the top directory of your Kitsune clone:
$ find . -name "*.less.css" -delete

Verify the LESS_BIN setting in settings_local.py. Then hard-refresh your pages on the browser via Ctrl + Shift + R.

Setting it up ¶

A great way to check that everything really is working is 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_kitsune.* TO kitsune@localhost IDENTIFIED BY '<YOUR_PASSWORD>';

The test suite will create and use this database, to keep any data in your development database safe from tests.

Running the tests ¶

Running the test suite is easy:

$ ./manage.py test -s --noinput --logging-clear-handlers

This may open a Firefox window, which will close automatically.

For more information, see the test documentation.

Redis: Redis
RabbitMQ: Celery and Rabbit
Elastic Search: Search
Email: Email from Kitsune

If you want to install Kitsune on an Apache server in a mod_wsgi environment, see Running Kitsune with mod_wsgi.