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.

General HOWTOs

Performing a database backup

The first thing to do before any upgrade activity is to backup your database.

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

Optimizing an upgraded database (optional)

After you have run the upgrade script related to your version (see below), you may want to optimize your database which can both save disk space and speed up access times.

# psql -h <database_host> -U <database_username> <database_name> -c "REINDEX DATABASE <database_name> FORCE;"
$ psql -h localhost -U omero omero -c "REINDEX DATABASE omero FORCE;"

# psql -h <database_host> -U <database_username> <database_name> -c "VACUUM FULL VERBOSE ANALYZE;"
$ psql -h localhost -U omero omero -c "VACUUM FULL VERBOSE ANALYZE;"

Restoring a database backup if something goes wrong

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, it's best to create a new database and configure your server to use it:

$ createdb -h localhost -U postgres -O omero omero_from_backup
$ pg_restore -Fc -d omero_from_backup beforE_upgrade.db.dump
$ bin/omero config omero.db.name omero_from_backup

Ensuring your OMERO.web media directories point to the right location when using FastCGI

When upgrading, if you have kept the extracted OMERO.server directory you will need to keep the media directories in sync with the correct version of OMERO.web. Your options are either to replace the entire stanza that you pasted into your Apache or nginx configuration by re-running bin/omero web config <webserver> or by just modifying the /appmedia and /media alias locations.

Per version upgrade instructions

4.3.x to 4.3.4

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

$ cd ~/omero_dist
$ bin/omero web stop
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.3.4.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.

Restart OMERO.web by the following command:

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

4.3.x to 4.3.3

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

$ cd ~/omero_dist
$ bin/omero web stop
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.3.3.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.

Restart OMERO.web by the following command:

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

4.3.x to 4.3.2

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

$ cd ~/omero_dist
$ bin/omero web stop
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.3.2.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.

Restart OMERO.web by the following command:

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

4.3.x to 4.3.1

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

$ cd ~/omero_dist
$ bin/omero web stop
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.3.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.

Restart OMERO.web with the following command:

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

4.2.x to 4.3.0

From OMERO Beta 4.2.0, configuration is stored using config.xml in the etc/grid directory under your OMERO.server directory. 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 web stop
$ bin/omero admin stop
$ cd ..
$ mv omero_dist omero_dist_old
$ tar jxvf omero-Beta4.3.0.tar.bz2
$ cp omero_dist_old/etc/grid/config.xml omero_dist/etc/grid

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 1 or 2 hours), please be patient and ensure you have performed a database backup as outlined under "First steps".

$ psql -h localhost -U omero omero < sql/psql/OMERO4.3__0/OMERO4.2__0.sql
Password for user omero:
...
...

ALTER TABLE
Time: 9.105 ms
ERROR:  check constraint "logicalchannel_check" is violated by some row
ERROR:  current transaction is aborted, commands ignored until end of transaction block
ERROR:  current transaction is aborted, commands ignored until end of transaction block

You have some metadata that will need to be fixed by running:

$ psql -h localhost -U omero omero < sql/psql/OMERO4.3__0/omero-4.2-data-fix.sql
Password for user omero:
...
...

Following a successful db upgrade, you can start the 4.3 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.

Restart OMERO.web with the following command:

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

4.2.x patch releases

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

$ cd ~/omero_dist
$ bin/omero web stop
$ 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 syncmedia
$ bin/omero web start
```

4.1.x to 4.2.1+

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 "First steps".

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

$ 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.

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

Update your database

$ 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

$ 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 <database_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

$ 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

Print this

Sections

Personal tools

Upgrade

General HOWTOs

Performing a database backup

Optimizing an upgraded database (optional)

Restoring a database backup if something goes wrong

Ensuring your OMERO.web media directories point to the right location when using FastCGI

Per version upgrade instructions

4.3.x to 4.3.4

4.3.x to 4.3.3

4.3.x to 4.3.2

4.3.x to 4.3.1

4.2.x to 4.3.0

Update your database

4.2.x patch releases

4.1.x to 4.2.1+

Update your database

OMERO.web upgrade

Additional (Optional) Services

4.0.x to 4.1.x

Update your database

4.0.x patch releases

3.2.x to 4.0.0

Step 1: Database backup

Step 2: Update your database

Step 3: Configuring server

Document Actions