OMERO.server upgrade ==================== 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 :community_plone:`mailing lists <>` of the development status. See the full details of OMERO |release| features in the :forum:`Announcements ` forum. .. note:: Given the :secvuln:`security issues <>` which prompted the 5.0.5 release, we **strongly recommend** you advise all your users to **update their passwords regularly**. 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. Upgrade check list ------------------ .. contents:: :local: :depth: 1 Check Prerequisities ^^^^^^^^^^^^^^^^^^^^ Before starting the upgrade, please ensure that you have obtained all the prerequisites for installation, documented for Unix and Windows. In particular, ensure that you are running a suitable version of PostgreSQL to enable successful upgrading of the database. File limits ^^^^^^^^^^^ You may wish to review the open file limits. Please consult the :ref:`limitations-openfiles` section for further details. Password salting ^^^^^^^^^^^^^^^^ With 5.0.0, the default JDBC password provider has been modified to add password salting support. This implies that once a server has been upgraded and deployed, if passwords are modified, you will not be able to easily revert to a configuration without salting. To keep using the legacy password provider without salting support, you will need to configure :term:`omero.security.password_provider` to use the legacy ``chainedPasswordProviderNoSalt`` as described in the :ref:`legacy_password_providers` section. Password usage ^^^^^^^^^^^^^^ The passwords and logins used here are examples. Please consult the :ref:`troubleshooting-password` 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. Re-indexing for search ^^^^^^^^^^^^^^^^^^^^^^ All OMERO databases created **prior to 5.0.1** were susceptible to a Lucene bug which could "hide" some search entries. For example, an image might show up in queries based on its name, but searching for a tag or similar might show nothing. **If you have experienced any issues with search in the past**, you should **strongly** consider reindexing your full text index, the process for which has been significantly stream-lined. See :ref:`search-reindexing` for more information. Web Plugin Updates ^^^^^^^^^^^^^^^^^^ 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. Troubleshooting ^^^^^^^^^^^^^^^ 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_plone:`community <>` page. Upgrade check ^^^^^^^^^^^^^ 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 :doc:`UpgradeCheck` page. Upgrade steps ------------- For all users, the basic workflow for upgrading your OMERO.server is listed below. Please refer to each section for additional details. .. contents:: :local: :depth: 1 Perform a database backup ^^^^^^^^^^^^^^^^^^^^^^^^^ The first thing to do before **any** upgrade activity is to backup your database. .. parsed-literal:: $ pg_dump -h localhost -U **db_user** -Fc -f before_upgrade.db.dump **omero_database** Copy new binaries ^^^^^^^^^^^^^^^^^ 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 :file:`config.xml` in the :file:`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: .. parsed-literal:: $ cd .. $ mv OMERO.server OMERO.server-old $ unzip OMERO.server-|release|-ice3x-byy.zip $ ln -s OMERO.server-|release|-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. Upgrade your database ^^^^^^^^^^^^^^^^^^^^^ .. only:: point_release .. warning:: This section only concerns users upgrading from a |previousversion| or earlier server. If upgrading from a |version| server, you do not need to upgrade the database. Run the upgrade script """""""""""""""""""""" You **must** use the same username and password you have defined during :doc:`unix/server-installation`. The |version| upgrade script should execute in a short time. The example below assumes you are upgrading from a |previousversion| server. .. parsed-literal:: $ cd OMERO.server $ psql -h localhost -U **db_user** **omero_database** < sql/psql/OMERO\ |version|\_\_0/OMERO\ |previousversion|\_\_0.sql Password for user **db_user**: ... ... status --------------------------------------------------------------------- + + + YOU HAVE SUCCESSFULLY UPGRADED YOUR DATABASE TO VERSION OMERO |version|\_\_0+ + + (1 row) Optimize an upgraded database (optional) """""""""""""""""""""""""""""""""""""""" 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. .. parsed-literal:: $ 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;' .. _upgrademergescript: Merge script changes ^^^^^^^^^^^^^^^^^^^^ 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 ``_. For further information on managing your scripts, refer to :doc:`installing-scripts`. If you require help, please contact the OME developers. Update your configuration ^^^^^^^^^^^^^^^^^^^^^^^^^ Environment variables """"""""""""""""""""" If you changed the directory name where the |release| 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. JVM memory settings """"""""""""""""""" Your memory settings should be copied along with :file:`etc/grid/config.xml`, but you can check the current settings by running :omerocmd:`admin jvmcfg`. See :ref:`jvm_memory_settings` for more information. Python Imaging Library """""""""""""""""""""" Since OMERO 5.0.0, `Pillow`_ is used as the default imaging library for Python instead of PIL. Refer to the installation page of `Pillow`_ documentation to install Pillow on your system. .. warning:: As mentioned in the Pillow installation section, if you installed PIL, you will need to remove it first before installing Pillow. Changes to OMERO.web URLs """"""""""""""""""""""""" In order to ease deployment and avoid errors for IIS (Windows production deployment) and Apache (notably CentOS/RHEL6) OMERO.web now defaults to being "mounted on ``/omero``". The new OMERO.web web server stanzas have redirects in them with the notable exception of IIS. Depending on your web server configuration you may need to visit your OMERO.web instance at ``http://example.com/omero/`` As a result of this your web server configuration stanza generated by the previous version of ``bin/omero web config`` has to be replaced with the new version. To generate the relevant configuration, please run ``bin/omero web config ``, update and restart your web server. Changes to OMERO.web config (Windows-only) """""""""""""""""""""""""""""""""""""""""" Starting with OMERO.web 5.0, the special configuration of "omero.web.cache_backend" is no longer required and may in fact cause issues. Please see the instructions under :ref:`using_iis` for how to remove the configuration. Restart your database ^^^^^^^^^^^^^^^^^^^^^ - Following a successful database upgrade, you can start the server. .. parsed-literal:: $ cd OMERO.server $ bin/omero admin start - If anything goes wrong, please send the output of ``bin/omero admin diagnostics`` to ome-users@lists.openmicroscopy.org.uk. - Start OMERO.web with the following command: :: $ bin/omero web start Restore a database backup ^^^^^^^^^^^^^^^^^^^^^^^^^ 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, .. parsed-literal:: $ createdb -h localhost -U postgres -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 .. seealso:: :legacy_plone:`Legacy <>` Legacy part of the OME website containing upgrade instructions for previous versions of the OMERO server.