Powerful. Flexible. Lovely.

Installation guide

Introduction

This guide describes the installation process for Debian and Ubuntu Linux. The guide was tested on Ubuntu 8.10 and Debian Lenny. If you have a different *nix OS, you should correct commands according to your package manager's command syntax. If you use an old distribution you may be have to install some software from sources (especially database drivers).

And what about Windows?

Using Windows as a production web server is a very bizzare idea, but you can follow the instructions found on this page to get a working copy of Orphereus on Windows.

Prerequisites

Make sure that you have the following software installed before you continue:

  1. Python >=2.5.2 (2.6 is recommended).
    Execute the following command to install the latest Python version:
    sudo apt-get install python
  2. MySQL >=5.0 or PostgreSQL >=8.3. PostgreSQL is recommended for production.
    Execute the following command To install the latest MySQL version:
    $ sudo apt-get install mysql-server
    Execute the following command to install the latest PostgreSQL version:
    $ sudo apt-get install postgresql
  3. Database driver
    For MySQL you should use MySQLDB:
    $ sudo apt-get install python-mysqldb
    For PostgreSQL you should use psycopg2:
    $ sudo apt-get install python-psycopg2
    If you want to use Oracle, visit cx_Oracle homepage and download appropriate package.
  4. Setuptools and Easy install
    To install Setuptools execute:
    $ sudo apt-get install python-setuptools
    To install Easy install execute:
    $ cd /tmp
    /tmp$ wget http://peak.telecommunity.com/dist/ez_setup.py
    /tmp$ sudo python ez_setup.py 
    
  5. Subversion client
    If you don't have Subversion, execute the following command:
    $ sudo apt-get install subversion

Dependencies

You can try to install Orphereus with all dependencies automatically with only one command (see the next chapter) but we strongly recommend you install all the dependencies manually.

Orphereus requires the following libraries:

  1. Pylons = 0.9.7 (pylons-1.0 won't work!)
  2. WebOb = 0.9.6.1 (newer versions might not work as well)
  3. SQLAlchemy >= 0.6.0
  4. ipcalc >= 0.1
  5. Mutagen >= 1.15
  6. Python Image Libary (pil) >= 1.1
  7. PyCaptcha >= 0.4
  8. html5lib >= 0.11
  9. lxml >= 2.0
  10. pygments >= 1.0

Note that optional plugins (such as HTML Compressor or Statistics Plotter) may require the following libraries:

  1. pytidylib
  2. matplotlib

Execute the following commands from root shell to install these libraries:

# easy_install pip

# pip install --upgrade Cython==0.11
# pip install --upgrade pylons==0.9.7
# pip install --upgrade webhelpers=0.6.4
# pip install --upgrade sqlalchemy==0.6.0
# pip install --upgrade WebOb==0.9.6.1
# pip install --upgrade WebTest==1.1
# pip install --upgrade flup==1.0.3.dev-20110405

# pip install --upgrade mutagen
# pip install --upgrade html5lib
# pip install --upgrade pil
# pip install --upgrade pygments
# pip install --upgrade ipcalc
# pip install --upgrade lxml
# pip install --upgrade psycopg2

# cd /tmp
# wget https://pypi.python.org/packages/2.4/P/PyCAPTCHA/PyCAPTCHA-0.4-py2.4.egg
# easy_install ./PyCAPTCHA-0.4-py2.4.egg

# pip install --upgrade numpy
# pip install --upgrade matplotlib
# pip install --upgrade pytidylib

Deployment

First you should download the sources and extract them into a temporary directory.

Let's say you have the sources in /tmp/orphie

Now you have two options: installing Orphereus automatically using SetupTools or performing a manual installation.

Execute the following commands to perform an automatic installation:

$ cd /tmp/orphie
$ sudo python setup.py install 

These commands will install all unsatisfied dependencies and will stop if some dependencies can't be installed.

Commands for manual installation (recommended):

$ cd /tmp/orphie
$ mkdir -p /opt/orphereus
$ cp -R * /opt/orphereus

Creating an empty database and a user with full access rights to it.

For PostgreSQL:

$ su postgres
$ createuser orphereus --no-superuser --no-createdb --no-createrole --login --pwprompt --encrypted
$ createdb --owner=orphereus --encoding=utf-8 orphereus
$ exit
You will be asked for password, choose one and remember it.

For MySQL:

$ mysql -u root -p
> CREATE DATABASE `orphereus` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
> GRANT ALL PRIVILEGES ON orphereus.* TO 'orphereus'@'localhost' IDENTIFIED BY 'myComplexPassword';

Creating a config file for Orphereus.

Copy or rename development.ini.TEMPLATE from the distribution to prod.ini. If you have chosen the automatic installation, place this file anythere (for example, /etc/orphereus/prod.ini), otherwise copy this file into the Orphereus directory (/opt/orphereus)

Now edit this file. First you should set the database parameters.

For MySQL set SQLAlchemy parameters to something like these:

sqlalchemy.url = mysql://orphereus:myComplexPassword@127.0.0.1/orphereus?use_unicode=0&charset=utf8
sqlalchemy.encoding=utf-8

For PostgreSQL:

sqlalchemy.url = postgres://orphereus:myComplexPassword@localhost/orphereus
sqlalchemy.convert_unicode = true
You can find example parameters for another databases in development.ini.TEMPLATE

Also you should set some important options:

# Place any random string here
core.hashSecret = paranoia

# Domain 
core.baseDomain= anoma.ch

# URL prefix for example, if you want to access Orphereus with 
# URL http://mysite.com/prefix/, you should set this parameter 
# into prefix/
core.urlPrefix = /

# Local path to uploads directory. Make sure 
# that it has correct permissions
core.uploadPath = /var/www/orphereus/uploads

# Local path to static files directory.
# IMPORTANT: Copy all files from /opt/orphereus/Orphereus/public
# directory into this directory!
core.staticPath = /var/www/orphereus/static

# URL for directory with static files
core.staticPathWeb = http://static.mysite.com/

# URL for uploads directory 
core.filesPathWeb = http://uploads.mysite.com/
Help for other options will be added later.

Generate egg info:

$ cd /opt/orphereus
$ python setup.py egg_info
Note that you should also run this command after plugin installation/removal.

Create database structure:

$ paster setup-app prod.ini
If previous steps are performed correctly, you will see something like this:
Running setup_config() from Orphereus.websetup
16:33:42,657 INFO [CORE] ---------- Core settings:
  < Skipped >
16:33:43,832 INFO [ORM (Orphereus.model)] COMPLETED ORM INITIALIZATION STAGE
16:33:43,835 INFO [Orphereus.websetup] Creating tables
16:33:44,286 INFO [Orphereus.websetup] Successfully setup
16:33:44,325 DEBUG [Orphereus.websetup] users: 0
16:33:44,329 INFO [Orphereus.websetup] Adding user with password 'first'
16:33:44,334 DEBUG [Orphereus.websetup] paranoia
16:33:44,357 DEBUG [Orphereus.websetup] 36515362b03e6c8879c166429f9e0e689697b405ac5cff73262e30e85acfc550342efcf9083b8bcd5034a5e226fca63cfd13207dc3f9fd05255ea255626da891
16:33:44,368 DEBUG [Orphereus.websetup] 1
16:33:44,404 DEBUG [Orphereus.websetup] extenions: 0
16:33:44,408 INFO [Orphereus.websetup] Adding extensions
16:33:44,523 DEBUG [Orphereus.websetup] tags: 0
16:33:44,526 INFO [Orphereus.websetup] Adding tag /b/
16:33:44,542 INFO [Orphereus.websetup] Completed
16:33:44,545 DEBUG [Orphereus.websetup] Calling deploy routines, registered plugins: 7
16:33:44,549 DEBUG [Orphereus.websetup] calling deploy routine <function deployHook at 0x032448F0> from: newsgenerator
16:33:44,634 INFO [newsfeed] Creating news tag...
16:33:44,650 DEBUG [Orphereus.websetup] calling deploy routine <function deployHook at 0x0322BAB0> from: example
16:33:44,654 INFO [OrphieBaseController] Page content not created
16:33:44,657 INFO [OrphieBaseController] Creating main page content
16:33:44,668 DEBUG [Orphereus.websetup] DEPLOYMENT COMPLETED

Testing

You can test your Orphereus installation by running

$ paster serve --reload prod.ini

and entering http://localhost:5000 into your browser's address bar.

Use this link to open administrative pages: http://localhost:5000

Note that the deployment procedure creates a superuser with the password 'first'

You should also create a startup script. An example named orphie-initscript can be found inside the Orphereus distribution.

Maintenance

To implement automatic unbans, integrity checks and clean-ups, create a shell script /opt/orphereus/maintenance.sh with the follwing content:

#!/bin/sh -e
cd /opt/orphereus
paster maintenance --config=prod.ini --path=/opt/orphereus RunAllObligatory

and add this line into your crontab:

00 */12 * * * /opt/orphereus/maintenance.sh

Web server integration

There are two basic server modes: SCGI (recommended) and stand-alone HTTP server (with or without reverse-proxying).

For SCGI mode, add the following line to the [server:main] section:

  use = egg:PasteScript#flup_scgi_thread

For the second one:

  use = egg:Paste#http

We recommend Lighttpd web server with SCGI.

Your lighttpd.conf should have the following opions:

  1. In server.modules:
    server.modules              = (
                "mod_scgi",
                "mod_fastcgi",
                "mod_expire",
                ...
                )
    
  2. Main virtualhost configuration:
    $HTTP["host"] =~ "^(|www\.)mysite\.com.*$" {
    server.document-root = "/opt/orphereus"
    accesslog.filename = "/var/log/lighttpd/orphereus.access.log"
    
    scgi.server = ("/" =>
    ( "ServerIPAddress" => (
    "host" => "127.0.0.1",
    "port" => 5000,
    "min-procs" => 1,
    "max-procs" => 2,
    "check-local" => "disable")
    ))
    }
    
  3. Static files virtualhost configuration:
    $HTTP["host"] =~ "^static\.mysite\.com.*$" {
    server.document-root       = "/var/www/orphereus/static"
    }
    
  4. Uploads virtualhost configuration:
    $HTTP["host"] =~ "^uploads\.mysite\.com.*$" {
    server.document-root       = "/var/www/orphereus/uploads"
    expire.url = ( "/" => "access plus 2 months")
    }