======
Selena
======

Installation
------------

Requirements
~~~~~~~~~~~~
Selena requires Python 2.7 which is included in the latest Ubuntu Server 12.04 LTS systems::

  $ sudo apt-get install python-dev python-virtualenv

Message queue
~~~~~~~~~~~~~

Selena communicates with a central queue with `Redis <http://redis.io/>`_ as the broker. Install redis::

  $ sudo apt-get install redis-server

Since lost tasks can always be resent, the durability guarantees that Redis
provides by default are not necessary. You can significantly speed up the queue
by commenting out the ``save`` lines from ``/etc/redis/redis.conf``.

We can check the status of the Redis server::

  $ redis-cli -h localhost -p 6379 -n 0 info

Virtual Environment
~~~~~~~~~~~~~~~~~~~

Let's create a virtual environment for Python in the user's home::

  $ virtualenv . --distribute --no-site-packages

System User
~~~~~~~~~~~

Unprivileged and not owned by a person::

  $ sudo adduser --home /home/selena selena
  $ sudo su - selena

In any shell the user can *activate* the virtual environment. As a result of
that, the default Python executable and helper scripts will point to those
within the virtualenv directory structure::

  $ which python
  /usr/local/bin/python
  $ . bin/activate
  (selena)$ which python
  /home/selena/bin/python

Database
~~~~~~~~

Selena uses and supports MySQL. To install MySQL invoke::

  $ sudo apt-get install mysql-server libmysqlclient-dev libmysqld-dev

You now have to create a database and a user for Selena system. You can find many tutorials for that on the Internet.


Cache
~~~~~

Selena requires some cache system like *memcached*. Install::

  $ sudo apt-get install memcached


Installing from pip
~~~~~~~~~~~~~~~~~~~

Simply invoke::

  (selena)$ pip install selena

Installing from sources
~~~~~~~~~~~~~~~~~~~~~~~

Alternatively, to live on the bleeding edge, you can clone the selena git
repository to ``project`` and install it manually::

  (selena)$ git clone git://github.com/allegro/selena.git project
  (selena)$ cd project
  (selena)$ pip install -e .


Selena Agent
~~~~~~~~~~~~

To function properly, Selena needs `Selena-agent <http://github.com/allegro/selena-agent>`_ package installed and configured.


Configuration
-------------

Create file /INSTALL_DIR/selena/settings-local.py and fill in the appropriate
data.

Fill MySQL connection data::

  DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'your database name',
        'USER': 'your database username',
        'PASSWORD': 'your database password',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'init_command': 'SET storage_engine=INNODB,character_set_connection=utf8,collation_connection=utf8_unicode_ci'
        }
    }
  }

Generate new secret keys::

  SECRET_KEY = 'very_unique_string'
  AES_SECRET_KEY = b'sixteen byte key'

Set the number of minutes that will be displayed by the service errors, example 30::

  ERROR_TIME_INTERVAL =  30

Define RQ queues. The `default` queue is required. You have to also define one queue for main selena agent, for example `agent_1`::

  RQ_QUEUES = {
      'default': {
          'HOST': '127.0.0.1',  # Redis host
          'PORT': 6379,  # Redis port
          'DB': None,
          'PASSWORD': None,
      },
      'agent_1': {
          'HOST': '127.0.0.1',
          'PORT': 6379,
          'DB': None,
          'PASSWORD': None,
     },
  }

You can define additional queues: `planner`, `archiving`, `dispacher`, `monitors`, `stats`. They are used as follows:

    *planner* - enable or disable planned technical breaks

    *archiving* - create partitions, archive data

    *dispacher* - run monitoring tasks for services

    *monitors* - collect results from agents

    *stats* - calculate statistics


You also have to configure cache. Sample cache configuration (for default `memcached` configs)::

    CACHES = {
        'default': {
            'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
            'LOCATION': '127.0.0.1:11211',