pandora/README

pan.do/ra - open media archive

== SETUP ==
pan.do/ra is known to work with Ubuntu 12.04, older versions of
Ubuntu or other distributions should work
if the dependencies are up to date.

To setup pan.do/ra, you need python, bazaar, pip and virtualenv
and several other python modules:

* Packages
(add pandora ppa to get all packages in the required version)

    apt-get install python-software-properties
    add-apt-repository ppa:j/pandora
    apt-get update

(install dependencies)
    apt-get install bzr git subversion mercurial \
            python-setuptools python-pip python-virtualenv ipython \
            python-dev python-imaging python-numpy python-psycopg2 \
            python-geoip python-html5lib python-lxml \
            postgresql postgresql-contrib rabbitmq-server \
            ffmpeg2theora ffmpeg \
            python-ox oxframe oxtimeline

* Pan.do/ra
Get code from bazzar
    cd /srv/
    bzr branch http://code.0x2620.org/pandora pandora
    cd pandora
    virtualenv .
    pip -E . install -r requirements.txt

    cd static
    bzr branch http://code.0x2620.org/oxjs

create local_settings.py and create site.jsonc in /srv/pandora/pandora
do noy copy settings.py but only add your changes to local_settings.py
(check https://wiki.0x2620.org/wiki/pandora/configuration
 and use settings.py / config.jsonc / config.*.jsonc as example)

create and configure database as described below
after that

create / update static files
    
    ./manage.py update_static 
    ./manage.py compile_pyc

* Database
  We use postgresql but other databases might also work
  (make sure you have the python bindings installed).

  create a postgresql database

    sudo -u postgres createdb  -T template0 --locale=C --encoding=UTF8 -O pandora pandora

  (setting locale to C is required to fix a bug in sort if set to UTF8)

  now add settings to local_settings.py:
    DATABASES = {
        'default': {
            'NAME': 'pandora',
            'ENGINE': 'django.db.backends.postgresql_psycopg2',
            'USER': 'pandora',
        }
    }

  and run ./manage.py syncdb to populate the database.

  Optionaly use pg_trgm to improve find speed (requires postgres 9.1 and postgresql-contrib)

    echo "CREATE EXTENSION pg_trgm;" | sudo -u postgres psql pandora
    ./manage.py sqlfindindex | ./manage.py dbshell
    echo "DB_GIN_TRGM = True" >> local_settings.py



* RabbitMQ
  For background tasks RabbitMQ is required, to install rabbitmq:

    sudo apt-get install rabbitmq-server

  and create permissions according to BROKER_* in local_settings.py i.e.:

    sudo rabbitmqctl add_user pandora box
    sudo rabbitmqctl add_vhost /pandora
    sudo rabbitmqctl set_permissions -p /pandora pandora ".*" ".*" ".*"


* H264
    for h264 videos, you need ffmpeg with x264 and libfaac enabled,
    you also need to install qt-faststart (from ffmpeg/tools)
    (you can use medibuntu.org packages or compile ffmpeg yourself)
    to enable h264 derivatives add "mp4" to video.formats in your config.jsonc


== Deployment ==
* Install upstart scripts
check etc/init for upstart scripts, adjust path and user and put into /etc/init

To run pan.do/ra in production, we use nginx, using apache2 is also possible.

* nginx setup
    sudo apt-get install nginx 

  add this to local_settings.py:
    XACCELREDIRECT = True

  setup nginx according to etc/nginx/vhost.in

* apache2 setup
    apt-get install apache2-mpm-prefork libapache2-mod-xsendfile

  add this to local_settings.py:
    XSENDFILE = True

  setup apache according to etc/apache2/vhost.in

now you can start pandora services:
  service pandora start
  service pandora-tasks start
  service pandora-encoding start

=== Updating ===
To update a pandora installation get the latest version from bzr by running
    ./update.sh

this will update pandora/oxjs/python-ox and list possible upgrades to the db

to update your database tables, use
   ./manage.py sqldiff -a
to check if there are changes and
   ./manage.py sqldiff -a | ./manage.py dbshell
to apply them.

=== Development ===
  in one terminal:
    ./manage.py runserver

  and background task in another:
    ./manage.py celeryd -B -Q default,encoding