Personal tools
  • We're Hiring!

You are here: Home → Documentation → OMERO v4.2.2 → OMERO.server → Upgrade
Version Warning
Warning: This section is documentation for an OLD release of our software!
 

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 server and client roadmaps 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 OMERO.registry for update notifications on startup. If you wish to disable this functionality you should do so now as outlined on the UpgradeCheck page.

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. More experienced users may wish to examine the DbUpgrade page for technical information about OMERO.server database upgrades and how to troubleshoot errors themselves.

Per version upgrade instructions

4.2.x patch releases

Note: You should always backup your database before performing an upgrade as outlined under the steps for upgrading from 3.2.x to 4.0.0 (found at the bottom of this page).

  • Stop your old server, and replace it with the new binaries: 

    $ cd ~/omero_dist
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.2.1.tar.bz2

  • Your server configuration is stored in "config.xml" under "etc/grid". If you would prefer not to reconfigure your server, copy that file over: 

    $ cd ~/omero_dist
$ mv ../omero_dist_old/etc/grid/config.xml etc/grid

  • If you have modified any of the other etc/grid files like default.xml or template.xml you will need to make those modifications in the new files. A typical example is an increased memory setting for the Blitz process in etc/grid/templates.xml.

  • Now, you should be ready to start the OMERO server: 

    $ cd ~/omero_dist
$ bin/omero admin start

  • If anything goes wrong, please send the output of bin/omero admin diagnostics to ome-users@lists.openmicroscopy.org.uk.

  • Configuration for OMERO.web changed significantly in 4.2.1 to ease many of the deployment issues on both Unix and Windows platforms. Therefore, it is not necessarily, or possible to copy your web settings.py, but rather you should see the "Web on Production" page for more information on setting up your web server. This can safely be done after the OMERO server is running.

    If you have already upgraded to 4.2.1 you should only restart OMERO.web by the following command: 

    $ cd ~/omero_dist
$ bin/omero web stop
$ bin/omero web start

4.1.x to 4.2.1+

Note: You should always backup your database before performing an upgrade as outlined under the steps for upgrading from 3.2.x to 4.1.x (found at the bottom of this page).

From OMERO Beta 4.0.0, configuration is stored using Java properties so no configuration file copies need happen. If you have not made any file changes within your OMERO.server distribution directory you are safe to follow the following upgrade procedure: 

$ cd ~/omero_dist
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.2.0.tar.bz2
$ cd omero_dist

Update your database

You must use the same username and password you have defined during installation. Once begun, the upgrade can take significant time on large databases (up to 2 or 3 hours), please be patient and ensure you have performed a database backup as outlined under the steps for upgrading from 3.2.x to 4.1.x.

Warning:: Unlike previous database upgrades, the move to OMERO4.2__0 may require manual intervention. After some initial processing, a report is run which checks for possible permission issues. More Info Here. If it finds any, an error message will be printed: 

ERROR ON omero_41_check:
Your database has data which is incompatible with 4.2 and will need to be manually updated
Contact ome-users@lists.openmicroscopy.org.uk for help adjusting your data.

If this happens, please send the full report to the OME team for assistance correcting the warnings. The steps to run the script are slightly different from previous upgrades as well. It is necessary to be in the same directory as omero-4.1-permissions-report.sql, and adding more flags to the command line will help detect errors sooner: 

$ cd ~/omero-dist/sql/psql/OMERO4.2__0                      
$ psql -v ON_ERROR_STOP=1 --pset pager=off -h localhost -U omero -f OMERO4.1__0.sql  omero 
Password for user omero:
...
...

To mail the output of the command to the team, you may want to pipe the output to a file: 

$ psql ... -f OMERO4.1__0.sql omero > upgrade.log

Following a successful db upgrade, you can start the 4.2 server. 

$ cd ~/omero-dist/
$ bin/omero admin start

OMERO.web upgrade

Configuration for OMERO.web changed significantly in 4.2.1 to ease many of the deployment issues on both Unix and Windows platforms. Therefore, it is not necessarily, or possible to copy your web settings.py, but rather you should see the "Web on Production" page for more information on setting up your web server. This can safely be done after the OMERO server is running.

Additional (Optional) Services

In addition to a database upgrade you may also want to consider if any of the additional services and optional installs would be of use to you.

  • Python Imaging Library (for OMERO.web and Figure Export functionality only) Packages should be available for your distribution from here

  • Matplot Lib (for OMERO.web only) Packages should be available for your distribution from here

  • NumPy Lib (for scripting services) This package may already have been installed as a dependency of Matplot Lib, above, but if not you will need to install it to use scripting services. NumPy is available from here

  • OMERO.tables can be installed by following the OmeroTables install guide.

  • Security By default, OMERO clients only need to connect to two TCP ports for communication with your OMERO.server: 4063 (unsecured) and 4064 (ssl). For more details please see here.

4.0.x to 4.1.x

Note: You should always backup your database before performing an upgrade as outlined under the steps for upgrading from 3.2.x to 4.0.0 (found at the bottom of this page).

From OMERO Beta 4.0.0, configuration is stored using Java properties so no configuration file copies need happen. If you have not made any file changes within your OMERO.server distribution directory you are safe to follow the following upgrade procedure: 

$ cd ~/omero_dist
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.1.0.tar.bz2
$ cd omero_dist
$ bin/omero admin start

  • 4.1.0 to 4.1.1 or newer:

    If you have configured OMERO.web for a production environment, you should copy the configuration files from your old distribution directory: 

    $ cp ~/omero_dist_old/lib/python/omeroweb/settings.py ~/omero_dist/lib/python/omeroweb

  • 4.0.x to 4.1.0:

    If you wish to configure OMERO.web you should follow the instruction on Install page.

Note: It is not recommended to use any older settings.py files with the 4.1.x.

You should also change any environment variables or directory references that may point to the wrong location.

Update your database

You must use the same username and password you have defined during installation. Once begun, the upgrade can take significant time on large databases (up to 2 or 3 hours), please be patient and ensure you have performed a database backup as outlined under the steps for upgrading from 3.2.x to 4.0.0.. 

$ cd ~/omero-Beta4.1.0
$ psql -h localhost -U omero omero < sql/psql/OMERO4.1__0/OMERO4__0.sql
Password for user omero:
...
...

4.0.x patch releases

Note: You should always backup your database before performing an upgrade as outlined under the steps for upgrading from 3.2.x to 4.0.0 (found at the bottom of this page).

From OMERO Beta 4.0.0, configuration is stored using Java properties so no configuration file copies need happen. If you have not made any file changes within your OMERO.server distribution directory you are safe to follow the following upgrade procedure: 

$ cd ~/omero_dist
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.0.3.tar.bz2
$ cd omero_dist
$ bin/omero admin start

If you have configured OMERO.web for a production environment, you should copy the configuration files from your old distribution directory: 

$ cp ~/omero_dist_old/lib/python/omeroweb/settings.py \
     ~/omero_dist/lib/python/omeroweb

You should also change any environment variables or directory references that may point to the wrong location.

3.2.x to 4.0.0

If your server is anything other than a Beta 3.2 series, you will first need to follow all required upgrades on the OMERO Trac before proceeding with these instructions.

Unlike previous upgrades, migrating from the 3.2.x series to 4.0.0 is essentially a full re-install but re-using your existing database and data files. Nevertheless, all the instructions under install should be followed before beginning with these instructions. In fact, starting with a bare database may be advisable to test out your installation. Also, be sure to put aside a significant amount of time for upgrading larger databases.

Steps:

  1. Perform a database backup
  2. Update your database from OMERO3A__11 to OMERO4__0
  3. Configure the Beta4.0.0 server to use your existing database and data files.

Step 1: Database backup

# pg_dump -h <database_host> -U <db_username> -Fc -f <dump_filename> <db_name>
$ pg_dump -h localhost -U omero -Fc -f before_upgrade.db.dump omero3

Step 2: Update your database

You must use the same username and password you have defined during installation. Once begun, the upgrade can take significant time on large databases (up to 2 or 3 hours), please be patient and ensure you have performed a database backup as above. 

$ cd ~/omero-Beta4.0.0
$ psql -h localhost -U omero omero3 < sql/psql/OMERO4__0/OMERO3A__11.sql
Password for user omero:
...
...

Step 3: Configuring server

$ cd ~/omero-Beta4.0.0
$ bin/omero config set omero.data.dir /OMERO
$ bin/omero config set omero.db.name omero3

If the omero.db.user and omero.db.pass for the omero3 database are different then those for the database you created during installation, then those should be configured as well.

Document Actions