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:
-
Perform a database backup
-
Update your database from
OMERO3A__11
to OMERO4__0
-
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.