OMERO.server Linux installation walk-through ============================================ This page walks through the process of installing OMERO.server on a machine using a Debian-based Linux distribution. .. note:: This page is generally applicable to Debian and Ubuntu installations, although there are some small differences which are noted when applicable during the walk-through. Distributions ------------- Whilst OMERO can be made to work on a wide range of Linux distributions, installation using a package manager is the most straightforward way to get an OMERO installation up and running. However, due to changes between releases of Ubuntu and Debian, there are some restrictions over which version of OMERO can be easily installed using the package manager to install and manage the OMERO prerequisites. ================== ================= ============== Distribution ZeroC Ice version OMERO version ================== ================= ============== Debian 7.0 3.4 4.4.x Debian 6.0 3.3 4.3.x, 4.4.x ------------------ ----------------- -------------- Ubuntu 12.04 (LTS) 3.4 4.4.x Ubuntu 11.10 3.4 4.4.x Ubuntu 11.04 3.3 4.3.x, 4.4.x Ubuntu 10.04 (LTS) 3.3 4.3.x, 4.4.x ================== ================= ============== .. note:: ZeroC_ Ice can always be built from source code for specific platforms. In the remainder of this guide you should adjust version numbers to suit the distribution that you are targeting. Prerequisites ------------- You require at least a clean minimal Debian or Ubuntu installation and a non-root user account that has sudo privileges. First you need to enable the contrib and non-free repositories by opening :file:`/etc/apt/sources.list` in an editor, e.g. **$ sudo vim /etc/apt/sources.list** and editing to add the following lines:: deb http://ftp.uk.debian.org/debian/ squeeze contrib deb-src http://ftp.uk.debian.org/debian/ squeeze contrib deb http://ftp.uk.debian.org/debian/ squeeze non-free deb-src http://ftp.uk.debian.org/debian/ squeeze non-free .. note:: For Ubuntu the repository names and locations are different to Debian but you need to enable the **main**, **restricted**, **universe** and **multiverse** repositories. You can do this either by editing :file:`/etc/apt/sources.list` directly, in which case the entries already exist but are commented out, or using Synaptic (10.04 & 10.10) or Ubuntu Software Center (11.04 onwards). Now you need to update your package lists to ensure that you get the latest packages including those from the repositories that you just enabled:: $ sudo apt-get update Java ^^^^ From Ubuntu 11.10 and onwards, you can install OpenJDK 7 using:: $ sudo apt-get install openjdk-7-jdk For earlier versions of Ubuntu, Oracle recently changed their distribution license (OSDL) which means that Debian and Ubuntu can no longer distribute Java in their package management systems. This means that you have to install the JDK separately as follows: If you are on Debian then:: $ sudo apt-get install lsb_release For both Debian and Ubuntu you can now:: $ sudo apt-get install git $ git clone https://github.com/flexiondotorg/oab-java6.git $ cd oab-java6/ $ sudo ./oab-java6.sh The script will run and you should see some output indicating progress. When you get your prompt back:: $ sudo apt-get install sun-java6-jdk You also need to ensure that the Sun/Oracle JDK is the active one as you end up with the OpenJDK also installed to satisfy dependencies along the way:: $ sudo update-alternatives --config java and select the correct java from the displayed list. OMERO dependencies ^^^^^^^^^^^^^^^^^^ Now you are ready to install the rest of your prerequisite software packages:: $ sudo apt-get install unzip build-essential mencoder $ sudo apt-get install python python-imaging python-numpy python-tables python-matplotlib $ sudo apt-get install zeroc-ice33 $ sudo apt-get install postgresql $ sudo apt-get install apache2 libapache2-mod-fastcgi .. note:: On Ubuntu 11.04 and earlier, ``python-tables`` does not install. You need to install ``liblzo`` otherwise OMERO.tables will fail to start:: $ sudo apt-get install liblzo2-2 OMERO installation ------------------ Once the prerequisites are installed and configured, the OMERO.server can be set up. First, a home needs to be created for the server and this directory moved into. For example, to install OMERO locally into a directory called 'apps' in your home directory, use the following:: $ mkdir apps $ cd apps $ mkdir OMERO $ cd OMERO OMERO |release| ^^^^^^^^^^^^^^^ Release versions of OMERO.server can downloaded from the :downloads:`OMERO downloads <>` page. Assuming that you downloaded a release version of OMERO.server, extract it from the zip archive: .. parsed-literal:: $ unzip OMERO.server-|release|-ice33-byy.zip Give your OMERO software install a nice local name to save some typing later, to reflect what you set :envvar:`OMERO_PREFIX` to in the :ref:`linux_configuration` section, and to make it easy to manage the installation of newer versions of the server at a later date: .. parsed-literal:: $ ln -s OMERO.server-|release|-ice33-byy OMERO.server Development server ^^^^^^^^^^^^^^^^^^ .. include:: development-server .. _linux_configuration: Configuration ------------- Environment variables ^^^^^^^^^^^^^^^^^^^^^ .. warning:: The :envvar:`OMERO_HOME` environment variable is used internally by OMERO. Unless you really know what you are doing, it is strongly recommended not to set this variable. Edit your :file:`.bashrc` file, e.g. **$ vim ~/.bashrc** and add the following:: export JAVA_HOME=/usr/lib/jvm/java-6-sun export ICE_HOME=/usr/share/Ice-3.3.1 export POSTGRES_HOME=/usr/lib/postgresql/8.4 export OMERO_PREFIX=~/apps/OMERO/OMERO.server export PATH=$PATH:$JAVA_HOME/bin:$ICE_HOME:$POSTGRES_HOME/bin:$OMERO_PREFIX/bin export PYTHONPATH=/usr/lib/pymodules/python2.6:$PYTHONPATH export LD_LIBRARY_PATH=/usr/share/java:/usr/lib:$LD_LIBRARY_PATH .. note:: You may wish to check PostgreSQL and Python versions by checking the directories themselves, since they may not correspond to those listed above. In particular check the version of Python that is installed. Newer versions of Ubuntu are installing Python 2.7 from APT by default. Now you need to make those changes take effect by getting your shell to apply them using the **source** built-in command:: $ source ~/.bashrc You can check that the new environment variables have taken by printing their values to the shell, e.g.:: $ echo $OMERO_PREFIX /home/ome/apps/OMERO/OMERO.server Database creation ^^^^^^^^^^^^^^^^^ Now you need to configure your prerequisites so that they are ready for OMERO to make use of. For the purposes of this walk-through you can use the following dummy data for the user account:: U: db_user P: db_password DB: omero_database .. note:: For a live or public server install these values should be altered to reflect your security requirements. You should also consider locking down your server machine but that is outside the scope of this document. Set up PostgreSQL:: $ sudo -u postgres createuser -P -D -R -S db_user $ sudo -u postgres createdb -O db_user omero_database $ sudo -u postgres createlang plpgsql omero_database Check that a database called "omerodb" has been created:: $ psql -h localhost -U db_user -l Update PostgreSQL host-based authentication to accept remote connections:: $ sudo sed '/127.0.0.1/s/md5/trust/' /etc/postgresql/8.4/main/pg_hba.conf \ > pg_hba.conf && sudo mv pg_hba.conf /etc/postgresql/8.4/main/pg_hba.conf .. note:: The backslash '\\' in the sed command above is used merely to indicate a line-break and should not be included in the executed command Restart PostgreSQL:: $ sudo /etc/init.d/postgresql restart Use netstat to verify that there is something listening on port 5432, this should be your PostgreSQL server:: $ netstat -an | egrep '5432.*LISTEN' which should display a line similar to the following:: tcp 0 0 127.0.0.1:5432 0.0.0.0:* LISTEN OMERO.server ^^^^^^^^^^^^ Now you can configure OMERO.server so that it can connect to the PostgreSQL database:: $ omero config set omero.db.name 'omero_database' $ omero config set omero.db.user 'db_user' $ omero config set omero.db.pass 'db_password' .. note:: If you altered any of these values earlier then you will need to change them to reflect your requirements You can also check the values that have been set using:: $ omero config get Create a home for your OMERO data. For example, to install the OMERO data locally into :file:`~/apps/OMERO/OMERO.data`, use the following command:: $ mkdir ~/apps/OMERO/OMERO.data Configure OMERO to find the data location:: $ omero config set omero.data.dir ~/apps/OMERO/OMERO.data You can now configure the empty PostgreSQL database using Omero's db script. You can accept the defaults for the first few values and enter a suitable password as required when prompted, e.g. "root\_password:: $ omero db script .. |sqlfile| replace:: OMERO\ |version|\ __0.sql The output of this should be a file named, e.g. |sqlfile| file in your current directory. You can now tell PostgreSQL to configure your new database .. parsed-literal:: $ psql -h localhost -U db_user omero_database < |sqlfile| At this point you should see a whole load of output from PostgreSQL as it installs the new OMERO database. If all has gone well, you should now be able to start OMERO.server using the following command:: $ omero admin start You should now be able to connect to your OMERO.server using an OMERO client such as OMERO.insight and the following credentials:: U: root P: root_password OMERO.web ^^^^^^^^^ To connect with the webclient or webadmin using the included Django development server:: $ omero config set omero.web.application_server development $ omero config set omero.web.debug True You should be able to start the Web server with:: $ omero web start Starting django development webserver... Validating models... 0 errors found Django version 1.1.1, using settings 'omeroweb.settings' Development server is running at http://0.0.0.0:4080/ Quit the server with CONTROL-C.