OMERO

Downloads
Feature List
Licensing

Page Contents

Previous topic

OMERO.server backup and restore

Next topic

OMERO upgrade checks

This Page

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 mailing lists of the development status. Finally, all the 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.

Note

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.

If you encounter errors during a 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.

See the full details of OMERO 5.0.0-rc1 features in the Announcements forum.

For all users, the basic workflow for upgrading your OMERO.server is listed below. Please refer to each section for additional details.

Warning

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 omero.security.password_provider to use the legacy chainedPasswordProviderNoSalt as described in the Legacy password providers section.

Warning

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, make sure to replace the values of db_user and omero_database with the actual database user and database name for your installation.

Perform a database backup

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

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 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.0.0-rc1-ice3x-byy.zip
$ cp OMERO.server-old/etc/grid/config.xml OMERO.server-5.0.0-rc1-ice3x-byy.zip/etc/grid

Note

ice3x and byy need to be replaced by the appropriate Ice version and build number of OMERO.server.

Upgrade your database

Run the upgrade script

You must use the same username and password you have defined during OMERO.server installation. The 5.0 upgrade script should execute in a short time.

From a 4.4.x server

$ cd OMERO.server-5.0.0-rc1-ice3x-byy.zip
$ psql -h localhost -U db_user omero_database < sql/psql/OMERO5.0__0/OMERO4.4__0.sql
Password for user db_user:
...
...
                           status
---------------------------------------------------------------------
                                                                    +
                                                                    +
                                                                    +
YOU HAVE SUCCESSFULLY UPGRADED YOUR DATABASE TO VERSION OMERO 5.0__0+
                                                                    +
                                                                    +

(1 row)

From a 5.0.0-beta1 server

$ cd OMERO.server-5.0.0-rc1-ice3x-byy.zip
$ psql -h localhost -U db_user omero_database < sql/psql/OMERO5.0__0/OMERO5.0DEV__6.sql
Password for user db_user:
...
...
                           status
---------------------------------------------------------------------
                                                                    +
                                                                    +
                                                                    +
YOU HAVE SUCCESSFULLY UPGRADED YOUR DATABASE TO VERSION OMERO 5.0__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.

$ 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;'

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 https://github.com/ome/scripts.

For further information on managing your scripts, refer to Installing new scripts. If you require help, please contact the OME developers.

Update your configuration

Environment variables

If you changed the directory name where the 5.0.0-rc1 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

If you modified your memory settings, these changes will be lost and you will need to update the memory settings for the new server. Refer to the JVM memory settings sub-section of the OMERO.server installation section (Unix or Windows) for more information.

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 <webserver>, update and restart your web server.

Restart your database

  • Following a successful database upgrade, you can start the server.

    $ cd OMERO.server-5.0.0-rc1-ice3x-byy.zip
    $ 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,

$ 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

See also

Legacy
Legacy part of the OME website containing upgrade instructions for previous versions of the OMERO server.