The OME team is committed to providing frequent, project-wide upgrades both with bug fixes and new functionality. We try to make these 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.

Per version upgrade instructions

4.1.x to 4.2.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.1.x.

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

For OMERO Beta 4.2.x webclient configuration is stored in var/lib/custom_settings.py file, so you need to generate that file by:

Please delete old version of custom_settings.py. It is strongly recommended to create new one by the following command.

• Settings (optional field can be blank).(It is no longer necessary to touch settings.py)

  $ bin/omero web settings
  You just installed OMERO, which means you didn't have settings configured in OMERO.web.
  Please enter the domain you want to run OMERO.web on (http://www.domain.com:8000/):http://web.openmicroscopy.org.uk/
  Please enter the Email address you want to send from (omero_admin@example.com): web@openmicroscopy.org.uk
  Please enter the SMTP server host you want to send from (smtp.example.com): smtp.openmicroscopy.org.uk
  Optional: please enter the SMTP server port (default 25): 
  Optional: Please enter the SMTP server username: 
  Optional: Password: 
  Optional: TSL? (yes/no): 
  Saved to ~/Desktop/omero/var/lib/custom_settings.py
  

• If you have configured OMERO.web for a production environment , you should set LOGDIR:

  LOGDIR = '/home/omero/weblog/'
  

• OPTIONAL: Multiple servers: in omero/var/lib/custom_settings.py add the following:

  • Server list:

    SERVER_LIST = (
        ('omero1.domain.com', 4064, 'omero1'),
        ('omero2.domain.com', 4064, 'omero2'),
        ...
    )
    

  • Pagination (defines how many images is shown per page):

    PAGE = 24
    

• If you have configured OMERO.web for a production environment, you should delete /home/omero/webdb including sqlite database from your old distribution directory.

• Reconfigure mod_python:

  <Location "/">
      SetHandler python-program
      PythonHandler django.core.handlers.modpython
      SetEnv DJANGO_SETTINGS_MODULE omeroweb.settings
      PythonDebug On
      PythonPath "['/home/omero/omero_dist/lib/python', '/home/omero/omero_dist/var/lib', '/home/omero/omero_dist/lib/python/omeroweb'] + sys.path"
  
  </Location>
  

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.

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.

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.

Troubleshooting

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.