All entries for Monday 04 June 2018

Deploying OMERO from scratch – how we did it!

Two of my main tasks as soon as I started this position in September 2017 (and, effectively, CAMDU started existing) were to establish an Electronic Lab Notebook system that could be used by multiple groups and to finally implement OMERO for the Division of Biomedical Sciences. Task 1 was relatively straightforward: two groups were already using Wordpress for their ELNs and there was plenty of expertise around. Task 2 was a completely different beast.

People spoke of OMERO in hushed tones. Multiple people mentioned trying to run an OMERO install and failing at it. No one knew much about it. We didn't have any infrastructure to run it at scale and offer it to the whole division.

We eventually got there. It took much longer, much more effort and some significant support from IT Services, but we have a working OMERO installation available to everyone who decides to use it. Even if it took a lot of work, each individual step was not daunting at all! On this blog post, I will try to walk through the whole process, step by step, detailing and explaining our decisions.

- Provisioning Infrastructure

As mentioned, we did not have any kind of infrastructure that would scale for the possible number of users we might have in the future. Our options were, then, either buying a new machine specifically for the task or talking to IT Services to see what they could offer. We are incredibly lucky for having a great Linux hosting team that provides free CPU, memory and limited storage. It's all based on virtual machines, which is great news when it comes to resiliency (multiple data centres around campus and so on). My experience dealing with them has been fantastic.

After a couple of meetings and a couple of weeks, we were just handed four new shiny VMs running CentOS 7, and already pre-installed with all the software prerequisites. We have decided to separate the web-facing server from the backend, dedicating one machine for each; that would make it easier to adjust necessary resources for each portion of the task at hand. We have also established a test/traning environment and a production environment. So two environments, each with two servers: that's how we used the 4 VMs we received.

Again, I cannot overstate how much the support from IT Services made our lives easier: not only we're using they equipment, but their support for any issues that have arisen over time has been incredible.

The observant reader will have noticed that I mentioned "limited storage" when talking about the resources we were able to obtain. That was absolutely fine for us: it turns out that the storage space for the actual data to be saved in our OMERO install was never an issue. A recent grant from the Wellcome Trust meant that we had just acquired a new petabyte storage array!

- The installation Process

Given that we already had servers with all prerequisites installed and ready to go, this went pretty smoothly. If you are reusing an old machine, I'd definitely recommend wiping it clean and starting from scratch. We had to slightly deviate from the official OMERO installation instructions since we were using two different machines for server and web client, but otherwise it was very by the book. Short description follows:

1) For the OMERO server:

- Download OMERO server (just a simple wget) and decompress it (just a simple unzip)

- Created a symlink to the unzipped folder named "OMERO.server". This makes the server folder path nicer to look at and will help you a lot in the future when updating OMERO versions.

- Basic server configuration: set data directory, database name, user and password, generate basic database and start using it. This followed the install instructions almost exactly, so I won't bother you with the details.

That's it! Start the omero-server service (we're using systemctl) and the server should be running and accepting connections on port 4063.

2) For the OMERO web client:

- Download OMERO server (just a simple wget) and decompress it (just a simple unzip)

- Created a symlink to the unzipped folder named "OMERO.py". This makes the server folder path nicer to look at and will help you a lot in the future when updating OMERO versions. (we're using a different name for this symlink to make sure we're not mixing server and web client up.)

- Create a Python virtual environment and install the web server requirements into it: you can use something like

$ virtualenv /home/user/omerowebvenv --system-site-packages

$ /home/user/omerowebvenv/bin/pip install --upgrade -r /home/user/OMERO.py/share/web/requirements-py27.txt

- Activate virtualenv:

$ source /home/user/omerowebvenv/bin/activate

- Finally, there are just a few configuration steps for the server:

$ OMERO.py/bin/omero config set omero.web.application_server wsgi-tcp

$ OMERO.py/bin/omero web config nginx --http "443" > OMERO.server/nginx.conf.tmp

$ OMERO.py/bin/omero config set omero.web.server_list '[[""]]'

- Now you can start the omero-web service:

$ sudo systemctl start omero-web

- Extra tools

A basic OMERO install has lots of functionality right out of the box. However, there are plenty of interesting extensions and tools out there to complement and enhance what it can do. We installed some of them in our servers: they tend to be very very straightforward to deploy and at least one of them is almost essential, in my view.

OMERO.figure is often described as the "killer app" when it comes to getting people to use OMERO. It is a fantastic tool that is a web-based Illustrator-like interface for creating (you guessed) figures. What makes it really shine, especially when compared to dedicated software like Adobe Illustrator, is the fact that it is, at all times, using raw pixel data in your figures. That means that changing LUTs, turning channels on and off, adjusting brightness and contrast and adding labels based on metadata are straightforward operations. It's a bit hard to convey exactly how incredible OMERO.figure is without showing it, so I'll just embed the demo recorded by the OME team:

Next up, a gentle bump on viewer quality: OMERO.iviewer is not radically different from the default image visualisation built into OMERO, but it has a few nice extra features that make it worth installing: multiple side-by-side viewers, ROI support, rendering settings and so on. Installation is incredibly straightforward and it has given me zero headaches.

Of course, that's great if you want to view a plane at a time, but if you want 3D rendering you're out of luck. That is, unless you also install FPBioImage. It is a Unity-based tool that renders Z-stacks as volumes and allows the user to navigate the space around it using keyboard and mouse. It works surprisingly well and it's pretty robust.

- LDAP integration

So this is where things get complicated, at least to my non-LDAP-knowing mind. Using University-level sign-in information sounded like a great idea, so we decided to go for it.

First things first: we had to talk to IT Services and ask for an LDAP service account, since they do not allow any anonymous queries on that system (with good reason!). They gave me credentials for a service account and I had absolutely no idea what to do with them. The LDAP documentation on the OMERO website is fairly comprehensive, or at least I imagine it is if you know what you're doing.

So I did what I always do if I don't know something: I started poking and prodding at the system, trying to figure out how things work. My best friend in this process was ldapsearch, which is very useful for querying LDAP systems and seeing the results. Enough time staring at incomprehensible strings and eventually I figured out how to configure our server the right way.

It was a long and complicated process: first, we set up a truststore and a keystore for Java to use. Some sample commands that might help:

1) Creating truststore from certificate:

$ cat QuoVadisRootCA2.cer | keytool -import -alias ldap -storepass <PASSWORDHERE> -keystore /home/user/.keystore -noprompt

2) Setting up OMERO to look for the truststore in the right place:

$ OMERO.server/bin/omero config set omero.security.trustStore /home/user/.keystore

$ OMERO.server/bin/omero config set omero.security.trustStorePassword <PASSWORDHERE>

3) Setting up keystore based on certificate:

$ keytool -importcert -file QuoVadisRootCA2.cer -keystore /home/user/.mystore

4) Pointing OMERO to the keystore:

$ OMERO.server/bin/omero config set omero.security.keyStore /home/user/.mystore

$ OMERO.server/bin/omero config set omero.security.keyStorePassword <PASSWORDHERE>

After all that, LDAP configuration was relatively straightforward following the documentation. One last tricky bit: by default, OMERO won't follow LDAP referrals, which might make it not work depending on the way your LDAP system is set up. We needed to run the following command to get it to work:

$ OMERO.server/bin/omero config set omero.ldap.referral ‘follow’

- What next?

Well, that was all it took to get OMERO up and running. In a follow-up post, we will talk about integration, maintenance and the issues we have encountered once everything was operational.

Erick Martins Ratamero : 04 Jun 2018 16:21 |  Comments (0) |  Close comments |  Report a problem