OMERO.server installation on OS X with Homebrew¶

Overview

This walkthrough demonstrates how to install OMERO on a clean Mac OS X system (10.9 or later) using Homebrew. Note that this demonstrates how to install OMERO.server from the source code via Homebrew, in addition to all its prerequisites. It is aimed at developers since typically MacOS X is not suited for serious server deployment.

These instructions are implemented in a series of automated scripts which install OMERO via Homebrew from a fresh configuration.

Prerequisites¶

Xcode¶

Homebrew requires the latest version of Xcode. Install Xcode and the Command Line Tools for Xcode from the App Store. If you have already installed it, make sure all the latest updates are installed.

Java¶

Oracle Java may be downloaded from the Oracle website.

After installing JDK 7 or JDK 8, check your installation works by running:

$ java -version
java version "1.8.0_51"
Java(TM) SE Runtime Environment (build 1.8.0_51-b16)
Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)

$ javac -version
javac 1.8.0_51

Requirements¶

All the requirements for OMERO will be installed under /usr/local. See also: Installation instructions on the Homebrew wiki.

Install Homebrew and make sure /usr/local/bin is prepended to your PATH:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ export PATH=/usr/local/bin:$PATH

Update Homebrew and run ‘brew doctor’ to fix potential issues beforehand:

$ brew update
$ brew doctor

Install git if not already present:

$ brew list | grep "\bgit\b" || brew install git

Install PostgreSQL database server:

$ export LANG=${LANG:-en_US.UTF-8}
$ export LANGUAGE=${LANGUAGE:-en_US:en}
$ brew install postgresql

You should install OMERO using Python 2.7 provided by Homebrew since it makes using Homebrew-provided modules simpler, for example the Ice python bindings needed by OMERO. For a more thorough description of the Homebrew solution, see the Homebrew and Python page. Note that the automated script linked above tests the OMERO installation using the Homebrew Python.

To install the Python provided by Homebrew:

$ brew install python

Check that Python is working and is version 2.7:

$ which python
/usr/local/bin/python
$ python --version
Python 2.7.9

The installation of OMERO via Homebrew depends upon two alternate repositories containing extra formulae: https://github.com/Homebrew/homebrew-science for the HDF5 formula and https://github.com/ome/homebrew-alt for all the OME-provided formulae and older versions of Ice. To add these, run:

$ brew tap homebrew/science
$ brew tap ome/alt

Note

The Homebrew formulae used below provide Python bindings. As described in Homebrew and Python, you should not be in an active virtual environment when you brew install them.

See the step01_deps.sh script for the steps described above.

OMERO installation¶

OMERO 5.3.4 server¶

To install and deploy the 5.3.4 release of OMERO.server, run:

$ brew install omero53 --with-nginx --with-cpp
$ export PYTHONPATH=$(brew --prefix omero53)/lib/python
$ export ICE_CONFIG=$(brew --prefix omero53)/etc/ice.config

This will install the OMERO server to /usr/local/Cellar/omero, which means you will find the log files in /usr/local/Cellar/omero/|release|/var/log. The binaries will be linked to /usr/local/bin:

$ which omero
/usr/local/bin/omero

Install Ice 3.6 extension for Python and OMERO python dependencies:

$ pip install -r $(brew --prefix omero53)/share/web/requirements-py27-all.txt
$ cd /usr/local
$ bash bin/omero_python_deps

Start database server:

$ pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log -w start

Create database and user:

$ createuser -w -D -R -S db_user
$ createdb -E UTF8 -O db_user omero_database
$ psql -h localhost -U db_user -l

Set database parameters in OMERO:

$ omero config set omero.db.name omero_database
$ omero config set omero.db.user db_user
$ omero config set omero.db.pass db_password

Create and run script to initialize the OMERO database:

$ export ROOT_PASSWORD=${ROOT_PASSWORD:-omero}
$ omero db script --password $ROOT_PASSWORD -f - | psql -h localhost -U db_user omero_database

Set up OMERO data directory:

$ export OMERO_DATA_DIR=${OMERO_DATA_DIR:-~/OMERO.data}
$ mkdir -p $OMERO_DATA_DIR
$ omero config set omero.data.dir $OMERO_DATA_DIR

See the OMERO installation script step02_omero.sh

Development server¶

If you wish to build OMERO.server from source for development purposes, using the git repository, first use Homebrew to install the OMERO dependencies:

$ brew install --only-dependencies omero

The default version of Ice installed by the OMERO formula is currently Ice 3.6.

Prepare a place for your OMERO code to live, e.g.:

$ mkdir -p ~/code/projects
$ cd ~/code/projects

If you want the development version of OMERO.server, you can clone the source code from the project’s GitHub account to build locally:

$ git clone --recursive git://github.com/openmicroscopy/openmicroscopy
$ cd openmicroscopy && ./build.py

Note

If you have a GitHub account and you plan to develop code for OMERO, you should make a fork into your own account and then clone this fork to your local development machine, e.g.

$ git remote add  git://github.com/YOURNAMEHERE/openmicroscopy
$ cd openmicroscopy && ./build.py

OMERO.web¶

Basic setup for OMERO using Nginx:

$ export HTTPPORT=${HTTPPORT:-8080}
$ omero web config nginx-development --http $HTTPPORT > $(brew --prefix omero53)/etc/nginx.conf

See installation script step03_nginx.sh

For detailed instructions on how to deploy OMERO.web in a production environment such as Nginx please see 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.

Startup/Shutdown¶

If necessary start PostgreSQL database server:

$ pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log -w start

Start OMERO:

$ omero admin start

Start OMERO.web:

$ omero web start
$ nginx -c $(brew --prefix omero53)/etc/nginx.conf

Now connect to your OMERO.server using OMERO.insight or OMERO.web with the following credentials:

U: root
P: omero

Stop OMERO.web:

$ nginx -c $(brew --prefix omero53)/etc/nginx.conf -s stop
$ omero web stop

Stop OMERO:

$ omero admin stop

See example script for a basic functionality test: step04_test.sh

Common issues¶

General considerations¶

If you run into problems with Homebrew, you can always run:

$ brew update
$ brew doctor

Also, please check the Homebrew Bug Fixing Checklist.

Below is a non-exhaustive list of errors/warnings specific to the OMERO installation. Some if not all of them could possibly be avoided by removing any previous OMERO installation artifacts from your system.

Database¶

Check to make sure the database has been created and ‘UTF8’ encoding is used

$ psql -h localhost -U db_user -l

This command should give similar output to the following:

                        List of databases

   Name         | Owner   | Encoding |  Collation  |    Ctype    | Access privileges
----------------+---------+----------+-------------+-------------+-------------------
 omero_database | db_user | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
 postgres       | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
 template0      | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/ome           +
                |         |          |             |             | ome=CTc/ome
 template1      | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/ome           +
                |         |          |             |             | ome=CTc/ome
(4 rows)

Macports/Fink¶

Warning: It appears you have MacPorts or Fink installed.

Follow uninstall instructions from the Macports guide.

PostgreSQL¶

If you encounter this error during installation of PostgreSQL:

Error: You must ``brew link ossp-uuid' before postgresql can be installed

try:

$ brew cleanup
$ brew link ossp-uuid

For recent versions of OS X (10.10 and above) some directories may be missing, preventing PostgreSQL from starting up. In that case, it should be sufficient to reinitialize a PostgreSQL database cluster as:

$ rm -rf /usr/local/var/postgres
$ initdb -E UTF8 /usr/local/var/postgres

szip¶

If you encounter an MD5 mismatch error similar to this:

==> Installing hdf5 dependency: szip
==> Downloading http://www.hdfgroup.org/ftp/lib-external/szip/2.1/src/szip-2.1.tar.gz
Already downloaded: /Library/Caches/Homebrew/szip-2.1.tar.gz
Error: MD5 mismatch
Expected: 902f831bcefb69c6b635374424acbead
Got: 0d6a55bb7787f9ff8b9d608f23ef5be0
Archive: /Library/Caches/Homebrew/szip-2.1.tar.gz
(To retry an incomplete download, remove the file above.)

then manually remove the archived version located under /Library/Caches/Homebrew, since the maintainer may have updated the file.

numexpr (and other Python packages)¶

If you encounter an issue related to numexpr complaining about NumPy having too low a version number, verify that you have not previously installed any Python packages using pip. In the case where pip has been installed before Homebrew, uninstall it:

$ sudo pip uninstall pip

and then try running python_deps.sh again. That should install pip via Homebrew and put the Python packages in correct locations.

OMERO.server installation on OS X with Homebrew¶

Prerequisites¶

Xcode¶

Java¶

Requirements¶

OMERO installation¶

OMERO 5.3.4 server¶

Development server¶

OMERO.web¶

Startup/Shutdown¶

Common issues¶

General considerations¶

Database¶

Macports/Fink¶

PostgreSQL¶

szip¶

numexpr (and other Python packages)¶

Page Contents

OMERO

Previous topic

Next topic

This Page

Navigation

OMERO.server installation on OS X with Homebrew¶

Prerequisites¶

Xcode¶

Java¶

Requirements¶

OMERO installation¶

OMERO 5.3.4 server¶

Development server¶

OMERO.web¶

Startup/Shutdown¶

Common issues¶

General considerations¶

Database¶

Macports/Fink¶

PostgreSQL¶

szip¶

numexpr (and other Python packages)¶

Page Contents

OMERO

Previous topic

Next topic

Quick search

This Page

Navigation