install.rst

Installation

Note

If you're looking into deploying Mutayzer in a production environment (as opposed to a local development installation), please see :ref:`deploy`.

Mutalyzer depends on a database server, Python 2.7, and several Python packages. Redis is a soft dependency. This section walks you through installing Mutalyzer with Redis and using PostgreSQL as database server, which is the recommended setup.

Note

All operating system specific instructions assume installation on a Debian 8 jessie system. You'll have to figure out the necessary adjustments yourself if you're on another system.

For example, RHEL6/CentOS6 is known to come with a version of libmagic which is incompatible with Mutalyzer.

The following steps will get Mutalyzer running on your system with the recommended setup:

• :ref:`install-postgresql`
• :ref:`install-redis`
• :ref:`install-virtualenv`
• :ref:`install-setup`

At the bottom of this page some :ref:`alternative setups <install-alternatives>` are documented.

If you're in a hurry

The impatient can run Mutalyzer without a database server and more such nonsense with the following steps:

$ pip install -r requirements.txt
$ python -m mutalyzer.entrypoints.website

This starts the website frontend on the reported port using an in-memory SQLite database.

Database server: PostgreSQL

Install PostgreSQL and add a user for Mutalyzer. Create a database (e.g. mutalyzer) owned by the new user. For example:

$ sudo apt-get install postgresql
$ sudo -u postgres createuser --superuser $USER
$ createuser --pwprompt --encrypted --no-adduser --no-createdb --no-createrole mutalyzer
$ createdb --encoding=UNICODE --owner=mutalyzer mutalyzer

Also install some development libraries needed for building the psycopg2 Python package later and add the package to the list of requirements:

$ sudo apt-get install libpq-dev
$ echo psycopg2 >> requirements.txt

This will make sure the Python PostgreSQL database adapter gets installed in the :ref:`install-virtualenv` section.

Redis

Mutalyzer uses Redis for non-critical fast storage such as statistics:

$ sudo apt-get install redis-server

Note

Redis is a soft dependency, meaning that Mutalyzer will run without it (but may lack some non-essential features such as caching of external resources).

Python virtual environment

It is recommended to run Mutalyzer from a Python virtual environment, using virtualenv. Installing virtualenv and creating virtual environments is not covered here.

Assuming you created and activated a virtual environment for Mutalyzer, install all required Python packages:

$ sudo apt-get install python-dev libmysqlclient-dev libxml2-dev libxslt-dev swig
$ pip install -r requirements.txt

Install Mutalyzer:

$ python setup.py install

Note

If you're planning on modifying the Mutalyzer source code, it might be convenient to install Mutalyzer in development mode:

$ python setup.py develop

Instead of copying the source code to the installation directory, this only links from the installation directory to the source code such that any changes you make to it are directly available in the environment.

Now might be a good time to run the unit tests:

$ py.test

Mutalyzer setup

Mutalyzer looks for its configuration in the file specified by the MUTALYZER_SETTINGS environment variable. First create the file with your configuration settings, for example:

$ export MUTALYZER_SETTINGS=~/mutalyzer/settings.py
$ cat > $MUTALYZER_SETTINGS
REDIS_URI = 'redis://localhost'
DATABASE_URI = 'postgresql://mutalyzer:*****@localhost/mutalyzer'

A script is included to setup the database:

$ mutalyzer-admin setup-database --alembic-config migrations/alembic.ini

You can now proceed to :ref:`run`.

Alternative setups

The remainder of this page documents some alternatives to the recommended setup documented above.

Database server: MySQL

Install MySQL and create a database (e.g. mutalyzer) with all privileges for the Mutalyzer user. For example:

$ sudo apt-get install mysql-server
$ mysql -h localhost -u root -p
> create database mutalyzer;
> grant all privileges on mutalyzer.* to mutalyzer@localhost identified by '*****';

The Python MySQL database adapter is a hard dependency regardless of your choice of database server, so it'll get installed in the :ref:`install-virtualenv` section.

In the :ref:`install-setup` section, make sure to use a MySQL database URI in the Mutalyzer settings file, e.g.:

DATABASE_URI = 'mysql://mutalyzer:*****@localhost/mutalyzer?charset=utf8'

Database server: SQLite

You probably already have all you need for using SQLite, so this section consists of zero steps.

Just note that in the :ref:`install-setup` section, you should use an SQLite database URI in the Mutalyzer settings file, e.g.:

DATABASE_URI = 'sqlite:////tmp/mutalyzer.db'