OMERO.server installation

See also

OMERO.server upgrade

Instructions for upgrading your OMERO.server installation.

OMERO.server Mac OS X installation walk-through with Homebrew

Instructions for installing your OMERO.server on Mac OS X using Homebrew.

OMERO.server Linux installation walk-through

Instructions for installing your OMERO.server on Debian/Ubuntu.

OMERO Installation for Mac OS X Snow Leopard (10.6)

A guide provided by Janek Claus and Kenneth Arcieri (NIH/NICHD/UCSS) for users wishing to install OMERO 4.1 on Mac OS 10.6, including details on how to build all dependencies from source. The OMERO 4.4 and 4.3 installs are almost identical to 4.2 and 4.1 (except for web client), so this guide will still be useful.

Omero Server Beta 4.2.0 installation on CentOS

A guide provided by Caterina Strambio De Castillia and Vanni Galli (University of Geneva/SUPSI in Lugano) for users wishing to install OMERO 4.1.1 or 4.2.0 on CentOS.

Limitations

Installation will require a “root” level account for which you know the password. If you are unsure of what it means to have a “root” level account, or if you are generally having issues with the various users/passwords described in this install guide, please see Which user account and password do I use where?.

Prerequisites

Note

The installation of these prerequisite applications is outside the scope of this document. For Linux distributions you should use the default package manager.

The following are necessary:

Java SE Development Kit (JDK) (1.6 or higher)

Java SE Downloads are available from http://www.oracle.com/technetwork/java/javase/downloads/index.html

UNIX systems, you can check which version of Java is currently available to you via your $PATH as follows:

$ which java
/usr/bin/java
$ java -version
java version "1.6.0"
Java(TM) SE Runtime Environment (build 1.6.0-b105)
Java HotSpot(TM) Server VM (build 1.6.0-b105, mixed mode)

Further, you can see if you have the Java compiler (Java SDK) installed and available via your $PATH as follows…

$ which javac
/usr/bin/javac
$ javac -version
javac 1.6.0

Python 2 (2.6 or later)

Check you have Python (and what version) by typing:

$ python --version
Python 2.7.5+

OMERO does not currently support Python 3.

The following are optional depending on what services you require:

Package	Functionality	Downloads
Pillow [1]	OMERO.web and Figure Export	Pillow page
Matplotlib	OMERO.web	Matplotlib page
NumPy (1.2.0 or higher) [2]	Scripting	Numpy/Scipy page
PyTables (2.1.0 or higher)	OMERO.tables	PyTables page
scipy.ndimage	Volume Viewer [3]	Numpy/Scipy page

[1]	Make sure to have libjpeg installed when building Pillow.

[2]	May already have been installed as a dependency of Matplot Lib.

[3]	Allows larger volumes to be viewed in the Volume Viewer.

Ice (3.3.x or 3.4.x)

Note

OMERO 5.0 supports Ice3.4, but this requires the correct version of OMERO.server (see Downloads). See “Do I use Ice 3.3 or Ice 3.4?” in the FAQ. If you have further questions, consult the Forums.

UNIX source downloads and binary packages are available from ZeroC. The latest compatible distribution is the 3.3.1 release. ZeroC does not provide binaries which work out of the box for Mac OS X Snow Leopard (10.6), so we recommend you follow the instructions for installation using Homebrew instead if this is your OS.

PostgreSQL (8.4 or higher)

PostgreSQL installed and configured with PL/pgSQL and to accept TCP connections. PostgreSQL 8.3 and earlier are not supported. See OMERO.server and PostgreSQL for specifics about each version.

OMERO.server

The OMERO.server.zip is available from the OMERO downloads page.

Environment variables

For the prerequisite software to run properly, your PATH, PYTHONPATH, and (DY)LD_LIBRARY_PATH environment variables must be configured. If you installed via a package manager such as rpm, apt-get, or macports, they should be set for you. If not correctly configured or if you installed manually to /opt/Ice-… or a similar location, you will need to set the values yourself.

If you are running a Linux distribution such as Debian or Ubuntu and have used APT to install the prerequisites then the installed software will have been installed to locations in your file system according to the Debian Policy Manual for software packaging. You can explicitly set your environment variables to reflect these install locations by editing the .bashrc (if on Linux) or .profile (if on Mac OS X) file which can be found within your home directory. For example, as of writing, on Debian and Ubuntu the following environment variables should be set:

export JAVA_HOME=/usr/lib/jvm/java-6-sun
export JRE_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 PYTHONPATH=/usr/lib/pymodules/python2.6:$PYTHONPATH
export DYLD_LIBRARY_PATH=/usr/share/java:/usr/lib/:$DYLD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/share/java:/usr/lib:$LD_LIBRARY_PATH
export PATH=$PATH:$JAVA_HOME/bin:$JRE_HOME/bin:$ICE_HOME/bin:$POSTGRES_HOME/bin

Please note that the precise details of these environment variables can change as new versions of software are released. You can retrieve the pathname for a file by using the which command. So if you are unsure what path to use in your environment variables, e.g. for the ICE_HOME variable you can execute the following command:

$ which icegridnode
/Users/ome/apps/OMERO.libs/bin/icegridnode

You can now set the ICE_HOME path to something similar to /Users/ome/apps/OMERO.libs/bin based upon the output from which, e.g.

export ICE_HOME=/Users/ome/apps/OMERO.libs/bin/icegridnode

As a last ditch effort, on a Linux or Mac OS X machine you can use the find command to help you discover whereabouts something is located in your filesystem. e.g.

$ find / -name "icegridnode" 2>/dev/null

However this might take a long time to run, especially on a big filesystem, so you might get a more timely solution by going to the OMERO forums.

If the command gives no output then perhaps Ice is not installed, in which case you should see the section above on installing Ice.

You can also add your OMERO bin directory to your path like so:

export PATH=$PATH:path-to-your-omero-install-directory/bin

When performing some operations the clients make use of temporary file storage and log directories. By default these files are stored below the users HOME directory in $HOME/omero/tmp, $HOME/omero/log and $HOME/omero/sessions (resp. $HOME\omero\tmp, $HOME\omero\log and $HOME\omero\sessions). If your home(~) directory $HOME is stored on a network, possibly NFS mounted (or similar), then these temporary files are being written and read over the network. This can slow access down.

The OMERO.server also access the $HOME/omero/tmp and $HOME/omero/log folders of the user the server process is running as (resp. $HOME\omero\tmp and $HOME\omero\log). As the server makes heavier use of these folders than the clients, if the users home(~) is stored on a network the server can be slowed down. To get round this for the OMERO.server you can define an OMERO_TEMPDIR environment variable pointing to a temporary directory located on the local file system e.g. /tmp (resp. C:\tmp\).

Creating a database as root

Probably the most important step towards having a working server system is having a properly configured database.

On most systems, a “postgres” user will be created which has admin privileges, while the UNIX root user itself does not have admin privileges. Therefore it is necessary to either become the postgres user or use sudo as below:

• Create a non-superuser database user and record the name and password. You will need to configure OMERO to use your username and password by setting the omero.db.name and omero.db.pass properties (below).

  # For PostgreSQL 8.4.x and later
  $ sudo -u postgres createuser -P -D -R -S db_user
  Enter password for new role:       # db_password
  Enter it again:       # db_password
  

  Warning

  For illustrative purposes, the default name and password for the user are db_user and db_password respectively. However, you should not use these default values for your installation but use your own choice of username and password instead.

• Create a database for OMERO to reside in

  $ sudo -u postgres createdb -O db_user omero_database
  

• Add the PL/pgSQL language to your database

  $ sudo -u postgres createlang plpgsql omero_database
  

• Check to make sure the database has been created, you have PostgreSQL client authentication correctly set up and the database is owned by the db_user user.

  $ psql -h localhost -U db_user -l
  Password for user db_user:
          List of databases
     Name         |  Owner   | Encoding
  ----------------+----------+-----------
   omero_database | db_user  | UTF8
   postgres       | postgres | UTF8
   template0      | postgres | UTF8
   template1      | postgres | UTF8
  (4 rows)
  

If you have problems, especially with the last step, take a look at OMERO.server and PostgreSQL since the authentication mechanism is probably not properly configured.

Location for the your OMERO binary repository

• Create a directory for the OMERO binary data repository. /OMERO (resp. C:\OMERO) is the default location and should be used unless you explicitly have a reason not to and know what you are doing.

• This is not where you want the OMERO application to be installed, it is a separate directory that OMERO.server will use to store binary data:

• You can read more about the OMERO binary repository.

  $ sudo mkdir /OMERO
  

• Change the ownership of the directory. /OMERO *must either be owned by the user starting the server (it is currently owned by the system root) or that user must have permission to write to the directory. You can find out your username and edit the correct permissions as follows:

  $ whoami
  ome
  $ sudo chown -R ome /OMERO
  

Installation

• Extract the OMERO tarball and note its location. Below it is referred to as: ~/Desktop/omero

• Optionally, review ~/Desktop/omero/etc/omero.properties which contains all default settings.

  You will need to open the file with a text editor. Do not edit the file. Any configuration settings you would like to change can be changed in the next step.

• Change any settings that are necessary using omero config, including the name and/or password for the ‘db_user’ database user you chose above or the database name if it is not “omero_database”. (Quotes are only necessary if the value could be misinterpreted by the shell. See link)

  $ cd ~/Desktop/omero
  $ bin/omero config set omero.db.name 'omero_database'
  $ bin/omero config set omero.db.user 'db_user'
  $ bin/omero config set omero.db.pass 'db_password'
  

• If you have chosen a non-standard OMERO binary repository location above, be sure to configure the omero.data.dir property.

• Create the OMERO database initialization script. You will be asked for the version of the script which you would like to generate, where both defaults can be accepted. Finally, you will be asked to enter and confirm password for your newly created OMERO root user.

  Warning

  For illustrative purposes, the default password for the OMERO rootuser is root_password. However, you should not use this default value for your installation but use your own choice of password instead.

  This should not be the same password as your Linux/Mac/Windows root user!

  $ cd ~/Desktop/omero
  $ bin/omero db script
  Please enter omero.db.version [OMERO5.0]:
  Please enter omero.db.patch [0]:
  Please enter password for new OMERO root user: # root_password
  Please re-enter password for new OMERO root user: # root_password
  Saving to ~/Desktop/omero/OMERO5.0__0.sql
  

• Initialize your database with the script.

  $ psql -h localhost -U db_user omero_database < OMERO5.0__0.sql
  

• Before starting the OMERO.server we should run the OMERO diagnostics script so that we check that all of our settings are correct, e.g.

  $ bin/omero admin diagnostics
  

• You can now start the server using:

  $ bin/omero admin start
  Creating var/master
  Initializing var/log
  Creating var/registry
  No descriptor given. Using etc/grid/default.xml
  

• If you would like to move the directory again, see bin\winconfig.bat --help, which gets called automatically on an initial install.

• You can now test that you can log-in as “root”, either with the OMERO.insight client or command-line:

  $ bin/omero login
  Server: [localhost]
  Username: [root]
  Password:         # root_password
  

JVM memory settings

To make your server production-ready, you will likely need to increase the JVM memory settings of your application descriptors. This is not done by default since it would prevent starting the server on some sites’ test instance but for production use a setting higher than 512MB is highly recommended.

To increase the JVM memory settings, you need to edit the etc/grid/templates.xml file under the OMERO.server directory.

It is highly recommended to increase the BlitzTemplate default JVM memory settings from -Xmx512M to -Xmx2048M and from XX:MaxPermSize=128m to XX:MaxPermSize=256M in production.

If working with large images generates OutOfMemory exceptions in the var/log/PixelData-0.log file, you may consider increasing the PixelDataTemplate default JVM memory settings to -Xmx1024M.

Once you have modified the templates.xml file, restart the server using:

$ bin/omero admin restart

See also

http://www.openmicroscopy.org/community/viewtopic.php?f=4&t=7400

Forum thread on PixelData JVM memory settings

Grid configuration

Section of the advanced server configuration documentation describing etc/grid/templates.xml.

OMERO.web and administration

Note

In order to deploy OMERO.web in a production environment such as Apache or IIS please follow the instructions under OMERO.web deployment.

Otherwise, the internal Django webserver can be used for evaluation and development. In this case, we need to turn debugging on, in order that static files can be served by Django:

$ bin/omero config set omero.web.application_server development
$ bin/omero config set omero.web.debug True

then start by

$ bin/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.

Once you have deployed and started the server you can use your browser to access the OMERO.web interface:

• http://localhost:4080/

  

  OMERO.webadmin login

Enabling movie creation from OMERO.

OMERO has the facility to create AVI/MPEG Movies from Images, which can be called from OMERO.insight. The page OMERO.movie gives details on how to enable them.

Post-installation items

Backup

One of your first steps after putting your OMERO server into production should be deciding on when and how you are going to backup your database and binary data. Please do not omit this step.

Security

It is also now recommended that you read the Server security and firewalls page to get a good idea as to what you need to do to get OMERO clients speaking to your newly installed OMERO.server in accordance with your institution or company’s security policy.

Advanced configuration

Once you have the base server running, you may want to try enabling some of the advanced features such as OMERO.dropbox or LDAP authentication. If you have *Flex data*, you may want to watch the HCS configuration screencast. See the Feature list for more advanced features you may want to use, and Advanced configuration on how to get the most out of your server.

Update notification

Your OMERO.server installation will check for updates each time it is started from the Open Microscopy Environment update server. If you wish to disable this functionality you should do so now as outlined on the OMERO upgrade checks page.

Troubleshooting

My OMERO install doesn’t work! What do I do now? Examine the Troubleshooting OMERO page and if all else fails post a message to our ome-users mailing list discussed on the Community support page.

OMERO diagnostics

If you want help with your server installation, please include the output of the diagnostics command:

$ bin/omero admin diagnostics

================================================================================
OMERO Diagnostics 5.0.0
================================================================================

Commands:   java -version                  1.6.0     (/usr/bin/java)
Commands:   python -V                      2.6.5     (/usr/bin/python)
Commands:   icegridnode --version          3.3.1     (/usr/bin/icegridnode)
Commands:   icegridadmin --version         3.3.1     (/usr/bin/icegridadmin)
Commands:   psql --version                 8.4.12    (/usr/bin/psql)

Server:     icegridnode                    running
Server:     Blitz-0                        active (pid = 28933, enabled)
Server:     DropBox                        active (pid = 28951, enabled)
Server:     FileServer                     active (pid = 28954, enabled)
Server:     Indexer-0                      active (pid = 28957, enabled)
Server:     MonitorServer                  active (pid = 28960, enabled)
Server:     OMERO.Glacier2                 active (pid = 28962, enabled)
Server:     OMERO.IceStorm                 active (pid = 28964, enabled)
Server:     PixelData-0                    active (pid = 28963, enabled)
Server:     Processor-0                    active (pid = 28972, enabled)
Server:     Tables-0                       active (pid = 28974, enabled)
Server:     TestDropBox                    inactive (enabled)

Log dir:    /home/omero/OMERO.server-5.0

Log files:  Blitz-0.log                    360.0 MB      errors=9    warnings=2458
Log files:  DropBox.log                    3.0 KB        errors=0    warnings=1
Log files:  FileServer.log                 0.0 KB
Log files:  Indexer-0.log                  506.0 KB      errors=0    warnings=90
Log files:  MonitorServer.log              2.0 KB
Log files:  OMEROweb.log                   710.0 KB      errors=5    warnings=2
Log files:  OMEROweb.log.1                 777.0 KB      errors=0    warnings=1
Log files:  OMEROweb.log.2                 776.0 KB      errors=0    warnings=2
Log files:  OMEROweb.log.3                 777.0 KB
Log files:  OMEROweb.log.4                 879.0 KB      errors=1    warnings=2
Log files:  OMEROweb.log.5                 258.0 KB
Log files:  OMEROweb_request.log           10.0 KB       errors=3    warnings=3
Log files:  PixelData-0.log                4.0 KB
Log files:  Processor-0.log                315.0 KB      errors=0    warnings=1
Log files:  Tables-0.log                   2.0 KB        errors=0    warnings=1
Log files:  TestDropBox.log                n/a
Log files:  master.err                     0.0 KB
Log files:  master.out                     0.0 KB
Log files:  Total size                     365.49 MB

Parsing Blitz-0.log:[line:30] => Server restarted <=
Parsing Blitz-0.log:[line:213] => Server restarted <=

Environment:OMERO_HOME=(unset)
Environment:OMERO_NODE=(unset)
Environment:OMERO_MASTER=(unset)
Environment:PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
Environment:ICE_HOME=(unset)
Environment:LD_LIBRARY_PATH=(unset)
Environment:DYLD_LIBRARY_PATH=(unset)

OMERO data dir: '/OMERO'    Exists? True    Is writable? True
OMERO.web status... [RUNNING] (PID 28736)