/doc_src/source/installation.rst

.. _installation:

.. include:: global.txt

Installation
============

Due to the early state of this project, there is a good chance that parts of
these instructions are out of date at any given time. If you run into any such
issue please let us know on our `issue tracker`_.

.. note:: 
    The following instructions are directed at what your eventual production
    environment will need. See :doc:`hacking` for details on setting up
    a development environment.

Assumptions
-----------
For the sake of sanity, good deployment practices, and uniformity, we're
going to make some assumptions. It is perfectly fine if you'd like to deviate,
but it will be *much* more difficult for us to help you:

* You are deploying or developing media-nommer in a virtualenv_. We highly
  recommend that and virtualenvwrapper_.
* You are running a flavor of Linux, BSD, Mac OS, or something POSIX compatible.
  While Windows support is achievable, it's not something we currently have
  the resources to maintain (any takers?).
* You have Python_ 2.y or later. Python_ 2.7 is preferred. Python_ 3.x is
  not currently supported.
* You have an `Amazon AWS`_ account, and can create S3_ buckets.

Requirements
------------

* Some flavor of Linux, Unix, BSD, Mac OS, or POSIX compliant OS.
* Python_ 2.6 or higher, with Python 2.7 recommended. Python_ 3.x is not
  supported (yet).

Installing
----------

For the sake of clarity, the media-nommer Python package contains
the sources for :doc:`feederd` and :doc:`ec2nommerd`. You will want to install
this package on whatever machine you'd like to run :doc:`feederd` on. You do
not need to do any setup work for :doc:`ec2nommerd`, as those are ran on an
EC2_ instance that is based off of an AMI that we have created for you.

Since we are not yet distributing media-nommer on PyPi, the easiest way is to 
install the package is through :command:`pip`::

    pip install txrestapi twisted
    pip install --upgrade git+http://github.com/duointeractive/media-nommer.git#egg=media_nommer
    
.. note::
    If you don't have access to :command:`pip`, you may download a tarball/zip, 
    from our `GitHub project`_ and install via the enclosed ``setup.py``. See 
    the ``requirements.txt`` within the project for dependencies.

We have to install Twisted before media-nommer because of an odd behavior
with :command:`pip`. 

.. tip:: Any time that you upgrade or re-install Twisted, you must also 
    re-install media-nommer.

Signing up for AWS
------------------

After you have installed the media-nommer Python package on your machine(s),
you'll need to visit `Amazon AWS`_ and sign up for the following services:

* SimpleDB_
* SQS_
* EC2_

It is important to understand that even if you already have an Amazon account,
you need to sign up to each of these services specifically for your account to
have access to said services. This is a very quick process, and typically
involves looking over an agreement and accepting it.

.. tip:: Signing up for these services is outside the scope of this document. 
    Please contact AWS_ support with questions regarding this step. Their
    community forums are also a great resource.

Fees are based on what you actually use, so signing up for these services will
incur no costs unless you use them.

AWS Management Console stuff
----------------------------

After you've signed up for all of the necessary services, there are a few
steps to work through within the `AWS Management Console`_. Sign in and take
care of the following.

Create a Security Group
^^^^^^^^^^^^^^^^^^^^^^^

You will need to create a ``media_nommer`` EC2 *Security Group* through the 
AWS_ management console for your EC2_ instances to be part of. You don't need
to add any rules, though, unless you want SSH access to the encoding nodes.

.. warning:: Failure to create an EC2 security group will result in
    media-nommer not being able to spawn EC2 instances, which means
    no encoding for you.

Create or import an SSH key pair
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Click on the **EC2** tab and find the **Key Pairs** link on the navigation bar.
You can then either create or import a key pair. Make sure to keep track of the
name of your keypair, as you'll need to specify it in your media-nommer
configuration later on.

.. warning:: Failure to create or import an SSH key pair will also lead to
    media-nommer being unable to spawn EC2 instances.
    
.. _installing_configuring:
    
Configuring
-----------

Once media-nommer is installed, create a directory to store a few files in.
Within said directory, create a file called :file:`nomconf.py`. You will
want to add these settings values (at minimum):

.. code-block:: python
    
    # The AWS SSH key pair to use for creating instances. This is just the
    # name of it, as per your Account Security Credentials panel on AWS.
    EC2_KEY_NAME = 'xxxxxxxxx'
    # The AWS credentials used to access SimpleDB, SQS, and EC2.
    AWS_ACCESS_KEY_ID = 'YYYYYYYYYYYYYYYYYYYY'
    AWS_SECRET_ACCESS_KEY = 'ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ'
    # The S3 bucket to store a copy of ``nomconf.py`` for nommer instances.
    # NOTE: CREATE A BUCKET AND CHANGE THIS VALUE BEFORE YOU START!
    CONFIG_S3_BUCKET = 'change-this-value'
    # The AWS security groups to create EC2 instances under. They don't need
    # any rules set.
    EC2_SECURITY_GROUPS = ['media_nommer']
    
See :py:mod:`media_nommer.conf.settings` for a full list of settings (and their
defaults) that you may override in your :file:`nomconf.py`.
    
Starting feederd
----------------

You will now want to start :doc:`feederd` using whatever init script or
init daemon you use. We have had good results with Supervisor_, but you can
use whatever you're comfortable with. Make sure that the server running
:doc:`feederd` is reachable by the machines that will be sending API requests
to start encoding jobs. Here is an example command string, assuming you're in
your top-level :file:`media-nommer` directory (not :file:`media_nommer`)::

    PYTHONPATH=media_nommer twistd -n --pidfile=feederd.pid feederd

Using
-----

From here, you'll want to select and start using a :ref:`client_api_libraries`.
These are what communicate with :doc:`feederd`'s RESTful web API, and ultimately
help get stuff done.