Note
This documentation is for OMERO 5.2. This version is now in maintenance mode and will only be updated in the event of critical bugs or security concerns. OMERO 5.3 is expected in the first quarter of 2017.
The OME team is committed to providing frequent, project-wide upgrades both with bug fixes and new functionality. We try to make the schedule for these releases as public as possible. You may want to take a look at the roadmap for exactly what will go into a release. We always inform our mailing lists of the development status.
See the full details of OMERO 5.2.7 features in the Announcements forum.
This guide aims to be as definitive as possible so please do not be put off by the level of detail; upgrading should be a straightforward process.
Before starting the upgrade, please ensure that you have reviewed and satisfied all the system requirements with correct versions for installation. In particular, ensure that you are running a suitable version of PostgreSQL to enable successful upgrading of the database, otherwise the upgrade script aborts with a message saying that your database server version is less than the OMERO prerequisite. If you are upgrading from a version earlier than OMERO 5.0 then first review the 5.0 upgrade notes regarding previous changes in OMERO.
You may wish to review the open file limits. Please consult the Too many open file descriptors section for further details.
The passwords and logins used here are examples. Please consult the Which user account and password do I use where? section for explanation. In particular, be sure to replace the values of db_user and omero_database with the actual database user and database name for your installation.
Check Deployment (Unix/Linux) or Deployment (Windows), what is the most recent OMERO.web deployment for the platform. If you generated configuration stanzas using omero web config which enables OMERO.web via Apache or Nginx, they will include hard-coded links to your previous version of OMERO. Therefore, you should regenerate your config files when upgrading, remembering to merge in any of your own modifications if necessary. You should carry out this step even for minor version upgrades as there may be fixes which require it.
Note
Since OMERO 5.2, the OMERO.web framework no longer bundles a copy of the Django package, instead manual installation of the Django dependency is required. It is highly recommended to use Django 1.8 (LTS) which requires Python 2.7. For more information see Python on the Version requirements page.
Also note that as of OMERO 5.2.6, support for Apache deployment is deprecated and is likely be dropped during the 5.3.x line.
While upgrading the server it is recommended to keep OMERO.web dependencies up to date to ensure that security updates are applied.
Nginx on Unix:
$ pip install --upgrade -r share/web/requirements-py27-nginx.txt
Apache (deprecated) on Unix:
$ pip install --upgrade -r share/web/requirements-py27-apache.txt
Windows:
$ pip install --upgrade -r share/web/requirements-py27-win.txt
Note
This is mainly for new major releases. If carrying out a minor release upgrade, you should check that updates will not break your set-up before performing this on your production system.
OMERO.web plugins are very closely integrated into the webclient. For this reason, it is possible that an update of OMERO will cause issues with an older version of a plugin. It is best when updating the server to also install any available plugin updates according to their own documentation.
All cached Bio-Formats memoization files created at import time will be invalidated by the server upgrade. This means the very first loading of each image after upgrade will be slower. After re-initialization, a new memoization file will be automatically generated and OMERO will be able to load images in a performant manner again.
These files are stored under BioFormatsCache in the OMERO data directory, e.g. /OMERO/BioFormatsCache. You may see error messages in your log files when an old memoization file is found; to avoid these messages delete everything under this directory before starting the upgraded server.
If you encounter errors during an OMERO upgrade, database upgrade, etc. you should retain as much log information as possible and notify the OMERO.server team via the mailing lists available on the community page.
All OMERO products check themselves with the OmeroRegistry for update notifications on startup. If you wish to disable this functionality you should do so now as outlined on the OMERO upgrade checks page.
For all users, the basic workflow for upgrading your OMERO.server is listed below. Please refer to each section for additional details.
The first thing to do before any upgrade activity is to backup your database.
$ pg_dump -h localhost -U db_user -Fc -f before_upgrade.db.dump omero_database
Before copying the new binaries, stop the existing server:
$ cd OMERO.server
$ bin/omero web stop
$ bin/omero admin stop
Your OMERO configuration is stored using config.xml in the etc/grid directory under your OMERO.server directory. Assuming you have not made any file changes within your OMERO.server distribution directory, you are safe to follow the following upgrade procedure:
$ cd .. $ mv OMERO.server OMERO.server-old $ unzip OMERO.server-5.2.7-ice3x-byy.zip $ ln -s OMERO.server-5.2.7-ice3x-byy OMERO.server $ cp OMERO.server-old/etc/grid/config.xml OMERO.server/etc/grid
Note
ice3x and byy need to be replaced by the appropriate Ice version and build number of OMERO.server.
Warning
This section only concerns users upgrading from a 5.1 or earlier server. If upgrading from a 5.2 server, you do not need to upgrade the database.
Versions of OMERO from 5.1.0 onwards require a Unicode-encoded database; without it, the upgrade script aborts with a message warning how the “OMERO database character encoding must be UTF8”. From psql:
# SELECT datname, pg_encoding_to_char(encoding) FROM pg_database;
datname | pg_encoding_to_char
------------+---------------------
template1 | UTF8
template0 | UTF8
postgres | UTF8
omero | UTF8
(4 rows)
Alternatively, simply run psql -l and check the output. If your OMERO database is not Unicode-encoded with UTF8 then it must be re-encoded.
If you have the pg_upgradecluster command available then its --locale option can effect the change in encoding. Otherwise, create a Unicode-encoded dump of your database: dump it as before but to a different dump file and with an additional -E UTF8 option. Then, create a Unicode-encoded database for OMERO and restore that dump into it with pg_restore, similarly to effecting a rollback. If required to achieve this, the -E UTF8 option is accepted by both initdb and createdb.
You must use the same username and password you have defined during OMERO.server installation. For a large production system you should plan for the fact that the upgrade script may take several hours to run.
$ cd OMERO.server
$ psql -h localhost -U db_user omero_database < sql/psql/OMERO5.2__0/OMERO5.1__1.sql
Password for user db_user:
...
...
status
---------------------------------------------------------------------
+
+
+
YOU HAVE SUCCESSFULLY UPGRADED YOUR DATABASE TO VERSION OMERO5.2__0 +
+
+
(1 row)
If you are upgrading from a server earlier than 5.1 then it suffices to run the earlier upgrade scripts in sequence before the one above. There is no need to download and run the server from an intermediate major release.
Note
If you perform the database upgrade using SQL shell, make sure you are connected to the database using db_user before running the script. See this forum thread for more information.
After you have run the upgrade script, you may want to optimize your database which can both save disk space and speed up access times.
$ psql -h localhost -U db_user omero_database -c 'REINDEX DATABASE "omero_database" FORCE;' $ psql -h localhost -U db_user omero_database -c 'VACUUM FULL VERBOSE ANALYZE;'
An additional database script is provided for fixing an error that affects only systems that were once upgraded from OMERO 4.4. More recent OMERO installations should skip this patching step.
The script patches OMERO 5.1 and 5.2 databases, runs quickly, and can be applied anytime, even under a running OMERO server. Although the problem has been sufficiently asymptomatic to go unnoticed for some time we nonetheless recommend that the patch is applied promptly.
$ psql -h localhost -U db_user omero_database < sql/psql/OMERO5.2__0/OMERO5.2-5.1-format-syntax-patch.sql
An unpatched system may exhibit serious problems if run with PostgreSQL 9.5. OMERO 5.2 does not support PostgreSQL 9.5 and the upgrade script for OMERO 5.3 will ensure that these PL/pgSQL functions are patched regardless of whether you used this provided script before that upgrade.
If any new official scripts have been added under lib/scripts or if you have modified any of the existing ones, then you will need to backup your modifications. Doing this, however, is not as simple as copying the directory over since the core developers will have also improved these scripts. In order to facilitate saving your work, we have turned the scripts into a Git submodule which can be found at https://github.com/ome/scripts.
For further information on managing your scripts, refer to OMERO.scripts. If you require help, please contact the OME developers.
If you changed the directory name where the 5.2.7 server code resides, make sure to update any system environment variables. Before restarting the server, make sure your PATH and PYTHONPATH system environment variables are pointing to the new locations.
Your memory settings should be copied along with etc/grid/config.xml, but you can check the current settings by running omero admin jvmcfg. See Memory configuration for more information.
FastCGI support was removed in OMERO 5.2 and OMERO.web can be deployed using WSGI (see Deployment (Unix/Linux) for more details). If you have already deployed OMERO.web using WSGI you should regenerate your config files, remembering to merge in any of your own modifications if necessary. Due to the nature of OMERO.web development for the 5.2.x line, you should carry out this step even for minor version upgrades as there may be fixes which require it.
If necessary ensure you have set up a regular task to clear out any stale OMERO.web session files as described in OMERO.web Maintenance (Unix/Linux) or OMERO.web Maintenance (Windows).
Since OMERO 5.2.6 support for Apache and mod_wsgi deployment is deprecated. It is recommended to use OMERO.web Nginx and Gunicorn deployment (Unix/Linux). Official support is likely to be dropped during the 5.3.x line.
Following a successful database upgrade, you can start the server.
$ cd OMERO.server
$ bin/omero admin start
If anything goes wrong, please send the output of omero admin diagnostics to ome-users@lists.openmicroscopy.org.uk.
Start OMERO.web with the following command:
$ bin/omero web start
If the upgraded database or the new server version do not work for you, or you otherwise need to rollback to a previous database backup, you may want to restore a database backup. To do so, create a new database,
$ createdb -h localhost -U postgres -E UTF8 -O db_user omero_from_backup
restore the previous archive into this new database,
$ pg_restore -Fc -d omero_from_backup before_upgrade.db.dump
and configure your server to use it.
$ bin/omero config set omero.db.name omero_from_backup
See also