OMERO.server installation overview

This section covers the installation of OMERO.server on UNIX and UNIX-like platforms. This includes all BSD, Linux and Mac OS X systems. Depending upon which platform you are using, you may find a more specific walk-through listed below.

See also

OMERO.server installation on CentOS 6 with Python 2.7

Instructions for installing OMERO.server from scratch on CentOS 6 with Python 2.7 and Ice 3.6.

OMERO.server installation on CentOS 7

Instructions for installing OMERO.server from scratch on CentOS 7 with Ice 3.6.

OMERO.server installation on Ubuntu 14.04 and 16.04

Instructions for installing OMERO.server from scratch on Ubuntu 14.04 and Ubuntu 16.04 with Ice 3.6.

OMERO.server installation on OS X with Homebrew

Instructions for installing and building OMERO.server on Mac OS X with Homebrew using our special formulas (i.e. from the source code via Homebrew). It is aimed at developers since typically MacOS X is not suited for serious server deployment. You do not need to refer to this page to install the prerequisites with Homebrew and then install the server zip from the downloads page.

Prerequisites

Installation will require:

• a clean, minimal operating system installation
• a “root” level account for which you know the password

Note

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?.

The installation and configuration of the prerequisite applications are mostly outside the scope of this document. For Linux distributions, use of the default package manager is recommended. For BSD systems, the ports system provides all the prerequisites. For MacOS X, Homebrew is recommended. This guide provides the package names to install for a number of contemporary systems. However, the names and versions provided vary between releases. Please do check for similar packages if the one documented here is not available for your system as it may be provided under an alternative name. “Debian” refers to Debian and derivative distributions such as Ubuntu. “RedHat” refers to RedHat and related distributions such as CentOS, Fedora and Scientific Linux.

• For Ubuntu you need to enable the universe repository. This should be enabled by default. If not enabled, it may be enabled by editing /etc/apt/sources.list directly, in which case the entries may already exist but are commented out, or by using Synaptic (10.04 and 10.10) or Ubuntu Software Center (11.04 onwards). Update your package lists to ensure that you get the latest packages:

  $ sudo apt-get update
  

  Install packages by running:

  $ sudo apt-get install package
  

  where package is the package name to install.

The following subsections cover the details for each package, in the order recommended for installation.

Java SE Runtime Environment (JRE)

If possible, install one of the following packages:

System	Package
BSD Ports	java/openjdk7
Debian	openjdk-7-jre
Homebrew	N/A (install Oracle Java)
RedHat	java-1.8.0-openjdk

OMERO works with the OpenJDK JRE provided by most systems, or with Oracle Java. Version 1.7 or later is required.

Your system may already provide a suitable JRE, in which case no extra steps are necessary. Linux distributions usually provide OpenJDK, and older MacOS X versions have Java installed by default. Oracle Java is no longer provided by BSD or Linux distributions for licensing reasons. If your system does not have Java available, for example on newer MacOS X versions, or the provided version is too old, Oracle Java may be downloaded from the Oracle website.

Warning

Security

Installing Oracle Java outside the system’s package manager will leave your system without regular distribution-supplied security updates, and so is not recommended.

To check which version of Java is currently available:

$ which java
/usr/bin/java
$ java -version
java version "1.7.0_51"
Java(TM) SE Runtime Environment (build 1.7.0_51-b13)
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode)

Python 2

Check you have Python (and check its version) by running:

$ python --version
Python 2.7.10

Note

OMERO does not currently support Python 3; you must use 2.7.

The following Python packages are required:

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

[1]	The currently supported version of the django module used by OMERO.web (1.8) requires Python 2.7. The older version (1.6) will work with Python 2.6 but lacks security support, and is consequently not recommended for production use. Python 2.7 and Django 1.8 are required for security support.

[2]	Make sure to have libjpeg installed when building Pillow. We currently do not support version 3.0+.

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

Note

Some of these can be ignored if you wish to forego some functionality but we recommend you just install everything. For example, scripting is enabled by default so should not be assumed optional even if you never expect your users to run scripts from the clients.

If possible, install the following packages:

System	Package
BSD Ports	lang/python27 graphics/py-pillow math/py-matplotlib math/py-numpy devel/py-tables science/py-scipy
Debian	python2.7 python-pil python-matplotlib python-numpy python-tables python-scipy
Homebrew	python pillow numpy matplotlib
RedHat	python

Note

CentOS 6 users should read OMERO.server installation on CentOS 6 with Python 2.7 and follow the instructions there to install Python and the required modules.

Ice

Note

OMERO supports 3.5 and 3.6 on UNIX and UNIX-like platforms. You must install the correct version of OMERO.server (see Downloads).

The Ice version may vary, depending upon the distribution version you are using. The Ice versions in currently supported versions of Debian and Ubuntu are shown in the Ice of the Version requirements page.

Using the latest version of Ice is recommended, where possible. If your package manager provides Ice packages, using these is recommended where possible. Distribution-provided packages often have additional bugfixes which are not present in the upstream releases.

If needed, source and binary packages are available from ZeroC. The latest release is available from the ZeroC website.

Note

CentOS 6 users should read OMERO.server installation on CentOS 6 with Python 2.7 and follow the instructions there to install Ice.

Note

ZeroC Ice can always be built from source code for specific platforms if a binary package is not available.

Note

With Ice 3.6, the Python bindings are provided separately. If your package manager does not provide Ice python packages, run pip install zeroc-ice to install the Ice Python bindings. See Using the Python Distribution for further details.

OMERO.web

Please install nginx and Gunicorn in order to run OMERO.web.

System	Packages
BSD Ports	www/nginx
Debian	nginx
Homebrew	nginx
RedHat	nginx

OMERO.scripts

If you wish to run the “Movie Maker” script, please install mencoder.

System	Packages
BSD Ports	multimedia/mencoder
Debian	mencoder
Homebrew	mplayer
RedHat	mencoder

Installation

Once the above prerequisites have been downloaded, installed and configured appropriately, the OMERO server itself may be installed. You may wish to create a user account solely for the purpose of running the server, and switch to this user for the next steps.

Server directory

Firstly, a directory needs to be created to contain the server. In this case ~/omero is used as an example:

$ mkdir -p ~/omero

Next, change into this directory:

$ cd ~/omero

OMERO.server

The release OMERO.server.zip is available from the OMERO downloads page. Download the version matching the version of Ice installed on your system before continuing.

Installing a development version from source is also possible. See the Installing OMERO from source section for further details. This is not recommended unless you have a specific reason not to use a release version.

Once you have obtained the OMERO.server zip archive matching the version of Ice installed, unpack it:

$ unzip OMERO.server-5.3.4-ice36-byy.zip

If your system does not provide an unzip command by default, install one of the following:

System	Package
BSD Ports	archivers/unzip
Debian	unzip
Homebrew	unzip
RedHat	unzip

Optionally, give your OMERO software install a short name to save some typing later, to reflect what you set OMERO_PREFIX to in the Environment variables section, below:

$ ln -s OMERO.server-5.3.4-ice36-byy OMERO.server

This will also ease installation of newer versions of the server at a later date, by simply updating the link.

Environment variables

If using distribution-provided packages such as Debian or RPM packages, or via the homebrew or macports package manager, it should not be necessary to set any environment variables. However, if using third-party packages for any required components, several variables may require setting in order for them to function correctly.

Please note that the precise details of these environment variables can change as new versions of software are released.

There are several methods for setting environment variables; which is most appropriate will depend upon how the OMERO server is started. Options include:

/etc/security/pam_env.conf

Global environment set at login by PAM

/etc/profile or /etc/profile.d/omero

Global Bourne shell defaults (also used by derived shells such as bash and zsh)

~/.profile

User’s Bourne shell defaults (also used by derived shells)

/etc/bash.bashrc

Global bash defaults

~/.bashrc, ~/.bash_profile or ~/.bash_login

User’s bash configuration.

If OMERO is started as a service using an init script, a global setting should be preferred. If being started by hand using a particular user, a user-specific configuration file may be more appropriate.

The following environment variables may be configured:

LD_LIBRARY_PATH (Linux) or DYLD_LIBRARY_PATH (MacOS X)

The Ice and PostgreSQL libraries must be on the library search path. If using the packages provided by your distribution, this will already be the case. If using third-party binary distributions the lib (or lib64 if present and using a 64-bit system) directory for each will require adding to the library search path.

OMERO_PREFIX

This is not strictly required, but may be set for convenience to point to the OMERO server installation, and is used in this documentation as a shorthand for the installation path.

OMERO_TMPDIR

Directory used for temporary files. If the home directory of the user running the OMERO server is located on a slow filesystem, such as NFS, this may be used to store the temporary files on fast local storage.

PATH

The search path must include the programs java, python, icegridnode and PostgreSQL commands such as psql. If using the packages provided by your distribution, this will already be the case. If using third-party binary distributions such as the ZeroC Ice package, Oracle Java, or PostgreSQL, the bin directory for each must be added to the path. The OMERO bin directory may also be added to the search path ($OMERO_PREFIX/bin if OMERO_PREFIX has been set).

PYTHONPATH

The Ice python directory must be made available to python. If using the Ice packages provided by your distribution, this will already be the case. If using the ZeroC ice package, add the python directory to the python path. For Ice 3.6, this should never be required.

Warning

The OMERO_HOME environment variable is used internally by OMERO. Unless you really know what you are doing, it is strongly recommended that you do not set this variable (see Setting the OMERO_HOME environment variable for details). You can use a different name of your choice instead, indicated by OMERO_PREFIX in this documentation.

After making any needed changes, either source the corresponding file or log back in for them to take effect. Run env to check them.

Note

CentOS 6 users should read OMERO.server installation on CentOS 6 with Python 2.7 and set the needed environment variables as documented.

Creating a 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 shown below.

For the purposes of this guide, the following dummy data is used:

Username: db_user
Password: db_password
Database: omero_database

Warning

Security

These dummy values are examples only and should not be used. For a live or public server install these values should be altered to reflect your security requirements—i.e. use your own choice of username and password instead. These should not be the same username and/or password as your Linux/Mac/Windows root user!

You should also consider restricting access to your server machine, but that is outside the scope of this document.

• Create a non-superuser database user and record the name and password used. You will need to configure OMERO to use this username and password later on.:

  $ sudo -u postgres createuser -P -D -R -S db_user
  Enter password for new role:       # db_password
  Enter it again:       # db_password
  

• Create a database for OMERO to reside in:

  $ sudo -u postgres createdb -E UTF8 -O db_user 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 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 which the 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
  omero
  $ sudo chown -R omero /OMERO
  

Configuration

• Optionally, review ~/omero/OMERO.server/etc/omero.properties, which contains all default settings. Do not edit this file—it is for reference only. Any configuration settings you would like to change can be changed in the next step. Alternatively, you can view a parsed version of the file under Configuration properties glossary or parse it yourself with omero config parse.

• 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 ~/omero/OMERO.server
  $ 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'
  

  You can also check the values that have been set using:

  $ cd ~/omero/OMERO.server
  $ bin/omero config get
  

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

  $ omero config set omero.data.dir /srv/omero
  

• Create the OMERO database initialization script. You will need to provide a password for the newly created OMERO root user, either by using the --password argument or by entering it when prompted. Note that this password is for the root user of the OMERO.server, and is not related to the root system user or a PostgreSQL user role.

  $ cd ~/omero/OMERO.server
  $ bin/omero db script --password omero_root_password
  

  Using OMERO5.3 for version
  Using 0 for patch
  Using password from commandline
  Saving to /home/omero/OMERO5.3__0.sql
  

Warning

Security

For illustrative purposes, the default password for the OMERO root user is shown as omero_root_password. However, you should not use this default values 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 or the database user!

• Initialize your database with the script.

  $ psql -h localhost -U db_user omero_database < OMERO5.3__1.sql
  

  At this point you should see some output from PostgreSQL as it installs the schema for new OMERO database.

• Before starting the OMERO.server, run the OMERO diagnostics script to check that all of the 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 multiple users have access to the system running OMERO you should restrict access to the OMERO.server/etc and OMERO.server/var directories, for example by changing the permissions on them:

  $ chmod 700 ~/omero/OMERO.server/etc ~/omero/OMERO.server/var
  

  You should also consider restricting access to the OMERO data repository. The required permissions will depend on whether you are using Advanced import scenarios.

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

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

  You will be prompted for an OMERO username and password. Use the username and password set when running bin/omero db script.

• If your users are going to be importing many files in one go, for example multiple plates, you should make sure you set the maximum number of open files to a sensible level (i.e. at least 8K for production systems, 16K for bigger machines). See Too many open files for more information.

JVM memory settings

The OMERO server starts a number of Java services. Memory settings for these are calculated on a system-by-system basis. An attempt has been made to have usable settings out of the box, but if you can afford to provide OMERO with more memory, it will certainly improve your overall performance. See Memory configuration on how to tune the JVM.

OMERO.web and administration

In order to deploy OMERO.web in a production environment such as Nginx please follow the instructions under Setting up OMERO.web.

Note

The internal Django webserver can be used for evaluation and development. In this case please follow the instructions under OMERO.web deployment for developers.

Enabling movie creation from OMERO.

OMERO has a facility to create AVI/MPEG Movies from images. The page OMERO.movie details how to enable it.

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 Configuration properties glossary on how to get the most out of your server.

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. Especially the Server fails to start and Remote clients cannot connect to OMERO installation sections are a good starting point.

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.3.4
================================================================================

Commands:   java -version                  1.7.0     (/usr/bin/java)
Commands:   python -V                      2.7.9     (/usr/bin/python)
Commands:   icegridnode --version          3.6.3     (/usr/bin/icegridnode)
Commands:   icegridadmin --version         3.6.3     (/usr/bin/icegridadmin)
Commands:   psql --version                 9.4.5    (/usr/bin/psql)

Server:     icegridnode                    running
Server:     Blitz-0                        active (pid = 30324, enabled)
Server:     DropBox                        active (pid = 30343, enabled)
Server:     FileServer                     active (pid = 30345, enabled)
Server:     Indexer-0                      active (pid = 30348, enabled)
Server:     MonitorServer                  active (pid = 30351, enabled)
Server:     OMERO.Glacier2                 active (pid = 30353, enabled)
Server:     OMERO.IceStorm                 active (pid = 30376, enabled)
Server:     PixelData-0                    active (pid = 30393, enabled)
Server:     Processor-0                    active (pid = 30394, enabled)
Server:     Tables-0                       inactive (disabled)
Server:     TestDropBox                    inactive (enabled)

OMERO:      SSL port                       4064
OMERO:      TCP port                       4063

Log dir:    /home/omero/OMERO.server-5.0.1-ice35-b21/var/log exists

Log files:  Blitz-0.log                    3.0 MB        errors=0    warnings=9
Log files:  DropBox.log                    4.0 KB        errors=0    warnings=1
Log files:  FileServer.log                 0.0 KB
Log files:  Indexer-0.log                  10.0 KB       errors=0    warnings=5
Log files:  MonitorServer.log              2.0 KB
Log files:  OMEROweb.log                   642.0 KB      errors=0    warnings=1
Log files:  OMEROweb_request.log           0.0 KB
Log files:  PixelData-0.log                7.0 KB        errors=0    warnings=4
Log files:  Processor-0.log                2.0 KB        errors=0    warnings=1
Log files:  Tables-0.log                   n/a
Log files:  TestDropBox.log                n/a
Log files:  master.err                     0.0 KB        errors=2    warnings=0
Log files:  master.out                     0.0 KB
Log files:  Total size                     3.83 MB

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

OMERO SSL port:4064
OMERO TCP port:4063
OMERO data dir: '/OMERO'        Exists? True    Is writable? True
OMERO temp dir: '/home/omero/tmp'        Exists? True    Is writable? True   (Size: 0)

JVM settings: Blitz-${index}                -Xmx621m -XX:MaxPermSize=512m -XX:+IgnoreUnrecognizedVMOptions
JVM settings: Indexer-${index}              -Xmx414m -XX:MaxPermSize=512m -XX:+IgnoreUnrecognizedVMOptions
JVM settings: PixelData-${index}            -Xmx621m -XX:MaxPermSize=512m -XX:+IgnoreUnrecognizedVMOptions
JVM settings: Repository-${index}           -Xmx414m -XX:MaxPermSize=512m -XX:+IgnoreUnrecognizedVMOptions

OMERO.web status... [RUNNING] (PID 16952)
Django version: 1.8.7

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.