1. Rasmus Scholer Sorensen
  2. oligomanager


Update, 11 Sep 2012: Introducing "staplemixer".
I've started development on a staplemixer, a simplified, light-weight, commandline version of oligomanager. Staplemixer is designed to be convenient to use without all the hazzle that comes with managing data in a database and the enforced naming conventions used in oligomanager. Staplemixer is to be designed with simplicity of use and function in mind.


To run oligomanager, you will need the following:
 - Python, wxPython and wxwidgets
 - Dabo
 - Database driver(s) and other python packages
 - Access to a database

Note that oligomanager currently runs best with python2.6 32-bit (you should first install this, then the corresponding packages). It is possible to run several versions of python side-by-side, as long as you remember to use the correct version when installing packages and running oligomanager.
If you already have a full-featured Python2.7 setup, you may also want to see if that works for you. (The main issue with Python2.7 has been unknown opcodes and segfaults produced by the wxPython implementation. By the time you read this, the bugs in wxPython may have been obliterated.)
Oligomanager was developed on Ubuntu Linux, but should run relatively smoothly on both Mac/Unix and Windows.

--- General installation guide ----

1. Instaling Python, wxWidgets and wxPython:
If python is not already installed, go to python.org and download version 2.6 or 2.7 for your OS. 

If wxPython is not already installed, go to wxpython.org and download version 2.8 for your OS. NB: At the moment, you will need the 32-bit version, even if you have 64-bit Windows.
You might also have to install wxwidgets. Go to wxwidgets.org and download version 2.8 for your OS.
Note: If you at some point get an "ImportError" for wx.aui, this means that your system has the wrong wx version installed. Remove wx2.6. If you then get an ImportError for wx, it means that wx is no longer recognized. On Ubuntu 12.04 this can be caused by python-wxgtk2.8 installing a path file in the wrong folder---e.g. using /usr/lib/wx/python/wx.pth instead of /usr/local/lib/python2.7/dist-packages. Try to copy the path file to this directory. This issue might also be fixed by (re)installing package python-wxversion.

Other packages that might need to be installed:
 - PyPI setuptools and optionally PIP (Both enables easy install and setting up packages via e.g. python setup.py install with setup.py being provided by an arbitrary package)
 - dateutil

2. Installing Dabo:
The best way to get dabo is to grap the most recent development files from the svn repository. You will need a Subversion (svn) client for this. Create a folder called e.g. "dabo-src" at some arbitrary location (example: C:\Dev\src-repos\dabo-src), enter the directory and use your svn client to get the dabo "trunk" from http://svn.dabodev.com/dabo/trunk.

Next, you need to make sure that python can find your dabo files. This can also be done in a couple of different ways, but I'd recommend putting a "path file" in your python's site-packages directory: Locate your site-packages directory, create a file called e.g. "dabo.pth". This file must contain a single line which is the path to your dabo-src folder. Example: Your Windownian python is located in C:\Python26.
Create the file C:\Python27\Lib\site-packages\dabo.pth, containing the following line:
C:\Dev\src-repos\dabo-src (for a windows setup where dabo is located in src-repos folder)

The paths for your python packages may vary according to you OS, distribution and version. Here are some examples of where to locate your .pth file:
Ubuntu 12.04: /usr/local/lib/python2.7/dist-packages/dabo.pth
Ubuntu 10.04: /usr/local/lib/python2.6/dist-packages/dabo.pth

3. Installing Database drivers:
You need to make sure you have the python database drivers, so you can connect from python to you database. If you have a postgres database, you will need the psycopg2 driver. (http://initd.org/psycopg/)

--- STEP-BY-STEP installation guides by OS ---
Ubuntu 12.04:
 - everything you need should be available via apt-get. The package names might vary according to your distribution, but they should be something like the below:
 - sudo apt-get install python2.6 
 - sudo apt-get install python-wxgtk2.8 python-dateutil psycopg2
 - sudo apt-get install svn hg
 - Get the latest version of dabo and set it up for your python, by following the instructions elsewhere on this page :)
 - Get oligomanager, as described below under "Mac".

Ubuntu 10.04 and below
 - everything you need should be available via apt-get. The package names might vary according to your distribution, but they should be something like the below:
 - sudo apt-get install python2.6 
 - sudo apt-get install python-wxgtk2.8 python-dateutil python-psycopg2
 - sudo apt-get install svn hg
 - Get the latest version of dabo (using svn) and set it up for your python, by following the instructions elsewhere on this page :)
 - Get oligomanager, as described below under "Mac".

 - Download and install xcode in order to get the gcc compiler. You probably have to sign up at Apple Developer Community to get it.
 - Download and install macports: http://www.macports.org/install.php
 - Get python: sudo port install python26 python_select
 - Get wxpython: sudo port install py-wxpython
 - Get dateutil and psycopg2: sudo port install py-dateutil py26-psycopg2
 - Get svn and hg clients: sudo port install subversion mercurial
 - Dabo: 
   1) Create a folder for dabo: mkdir ~/dev && mkdir ~/dev/src-repos && mkdir ~/dev/src-repos/dabo && cd ~/dev/src-repos/dabo
   2) Get the latest version of dabo: svn checkout http://svn.dabodev.com/dabo/trunk dabo-trunk
   3) Locate your macport's python site-packages folder
   4) Add a text file in your site-packages folder with name "dabo.pth" and content "/Users/<your user name>/dev/src-repos/dabo"
 - Get oligomanager (if you do not already have it) by running the following line:
    1) Go to the folder where you want oligomanager to be located (e.g. ~/dev/src-repos/)
    2) hg clone https://bitbucket.org/rasmusscholer/oligomanager
 - Run oligomanager by going to <folder>/oligomanager/oligomanager and run "python2.6 oligomanager.py"
 - If you get an Xlib warning, you might have to install xorg-server: sudo port install xorg-server

For windows, everything is done by downloading installers from the net.
Python: http://python.org/download/releases/2.6.6/ (go for the 32 bit version)
Add python to your environment path: computer-properties -> advanced system settings -> advanced, "environment variables" -> find the path variable, add the folder where you installed python.
WxPython: http://www.wxpython.org/download.php (python 2.6 and 32 bit version)
SetupTools: http://pypi.python.org/pypi/setuptools#downloads (python 2.6 version, windows installer)
Dateutil: http://labix.org/python-dateutil - download http://labix.org/download/python-dateutil/python-dateutil-1.5.tar.gz and extract it. Run python setup.py install
Psycopg2: http://initd.org/psycopg/download/ -> http://www.stickpeople.com/projects/python/win-psycopg/ - download http://www.stickpeople.com/projects/python/win-psycopg/psycopg2-2.4.2.win32-py2.6-pg9.0.4-release.exe (32 bit version for python 2.6)
Download and install subversion (svn) and mercurial (hg) clients.
Get dabo and set it up with python as described under "Mac".
Get oligomanager as described under "Mac".

--- Checking your setup ---

When you have installed the pre-requisites above, you can check your setup by doing the following:
1) Open a console, and launch python by typing 'python'. If you are on windows, you might have to add the python installation directory to your path environment variable. (Google is your friend...)
2) In python, type:
import wx
import psycopg2 (if you plan on using postgresql.)
import dateutil
import dabo 

If you get an import error with either of these, you have done something wrong.

-- 4. Database Configuration: ---
Finally, you will also need to have access to a database. Oligomanager supports many different kinds of databases (via the dabo framework), e.g. PostgreSQL, MySQL, FirebirdDB and even file-based databases like SQlite. 

I recommend using Postgresql, which is free and open-source (most database software are). You can find tons of guides on the internet on how to set it up. 

My recommend setup is to have a server with a common "oligomanager" database for all persons in your lab, preferentially running PostgreSQL. If you do not have access to a database server already, you can download PostgreSQL from postgresql.org and install it on a server or your local computer. Alternatively, use one of the file-based databases on your local computer.

Laying out your database: When you have access to a database server, you need to create a database in which oligomanager can save it's data. You can take a look at the file sql/om_database.sql for hints. This file also includes information needed to create the base layout (schema) of the database.

You can use dabo's CxnEditor (located in dabo-trunk/ide/CxnEditor.py) to create a connection file for connecting oligomanager to your database. Save the connection file to oligomanager/db directory.

All *.cnxml files located in the /db subdirectory are automatically loaded.

Default login for localhost database can be:
 database: oligomanager
 user: oligomanager
 pass: NedSeeman

----- RUNNING OligoManager -------

Change folder and run the oligomanager.py start-up script with python:
 - cd oligomanager/oligomanager
 - python oligomanager.py

On windows, you can also just run the go.bat script located in the same folder as oligomanager.py