PACKAGER'S README FOR OMERO-5.0.0 Damien Goutte-Gattat 1. DISCLAIMER This file does not come from the OMERO project and the OMERO developers don't endorse anything of it. Official documentation and instructions for installing and running OMERO server should be looked for at . 2. SYSTEM USERS AND GROUPS The OMERO server installed by this SlackBuild is intended to be run by a dedicated `omero' user. That user will own most of the OMERO files and must also have a existing, writable HOME directory. The `doinst.sh' script will automatically create that user if it does not already exist in `/etc/passwd'. The new account will have a UID of 270, a HOME directory in `/var/lib/omero' and will belong to the `omero' group; that group will also be automatically created if needed. To use another UID/GID or another HOME directory, either edit the `doinst.sh' script before running the SlackBuild, or create the group and user yourself before installing the package. 3. INSTALLATION LAYOUT There are four locations on the filesystem that will be used by the package: - the OMERO main directory, `/opt/omero', where the programs and libraries themselves will be installed; - the OMERO configuration directory, `/etc/omero', will store all the configuration files; they should normally be in OMERO's main directory, but I prefer to have them in `/etc', so I symlink `/opt/omero/etc' to `/etc/omero' to allow OMERO to find them; - the `omero' user's home directory, by default `/var/lib/omero' (as created by the `doinst.sh' script, see above); it will hold some temporary files and the current runtime configuration of OMERO, if different from the default built-in configuration; - the data repository, where OMERO will store the raw data files, `/OMERO' by default. The four locations must be readable by the `omero' user; the main directory, the `omero' user's home directory, and the data repository must be writable by that user. The main and configuration directories are hardcoded in the SlackBuild and the associated scripts, but not in OMERO itself; you may change them if you want before running the SlackBuild. The `omero' user's home directory can be changed at any time with usermod(8). Restart OMERO for the change to take effect. The data repository is defined by the key `omero.data.dir' in the main configuration file `/etc/omero/omero.properties'. Note that OMERO 5.0.0 needs another directory, defined by the key `omero.managed.dir'. In the default configuration file, this key uses the value of the `omero.data.dir' key as follows: omero.data.dir=/OMERO/ omero.managed.dir=${omero.data.dir}/ManagedRepository but OMERO then complains that `omero.data.dir' is undefined, so you should really specify a full path for `omero.managed.dir`, even if the directory is located below `omero.data.dir`: omero.data.dir=/OMERO/ omero.managed.dir=/OMERO/ManagedRepository 4. OMERO CONFIGURATION AND CONTROL There are many parameters controlling OMERO's behavior, but most of them may be left unmodified for the first run. The only parameters that must be explicitly set before running OMERO are those defining the data repository (`omero.data.dir' and `omero.managed.dir') and the database backend (`omero.db.*'), in `/etc/omero/omero.properties'. Starting and stoping OMERO is done with the `/etc/rc.d/rc.omero' control script. Before starting OMERO the first time, run `/etc/rc.d/rc.omero init'; the script will read the configuration files and ensure the data repository and the database backend are ready to use (this includes automatically creating the PostgreSQL account and database if those specified in `/etc/omero/omero.properties' does not exist on the server). This initialization step should be performed each time a configuration file is modified. 5. OMERO.web The Django-based web application OMERO.web is not enabled by default, as it requires some configuration. Add the following lines to the OMERO configuration file /etc/omero/omero.properties: ---8<---------------------------------------------------------------- omero.web.application_server=fastcgi-tcp omero.web.application_server.host=localhost omero.web.application_server.port=4080 omero.web.application_host=:80 omero.web.debug=false --->8---------------------------------------------------------------- Then, edit the control script /etc/rc.d/rc.omero to automatically start and start the FCGI workers alongside the OMERO server itself: ---8<---------------------------------------------------------------- OMERO_WEB_ENABLED=yes --->8---------------------------------------------------------------- Then, you need to install and configure the Apache HTTP server to actually serve the application. NOTE: Do *not* follow the official OMERO documentation from this point, as it does not support running OMERO.web with Apache 2.4 and the mod_proxy_fcgi module. In particular, the configuration lines produced by the following command: omero web config apache are not suitable for Apache 2.4. Instead, add the following stanza to your Apache configuration: ---8<---------------------------------------------------------------- RewriteEngine On RewriteRule ^/?$ /omero/ [R] ProxyPass /webclient fcgi://localhost:4080 ProxyPass /webadmin fcgi://localhost:4080 Alias /static /opt/omero/lib/python/omeroweb/static Options -Indexes +FollowSymLinks Require all granted --->8---------------------------------------------------------------- (Make sure the mod_rewrite, mod_proxy and mod_proxy_fcgi modules are loaded. This is normally done in the default httpd configuration file provided by Slackware.) Start the web server. OMERO.web should now be reachable at /webclient> (for the main client interface) and at /webadmin> (for the administration interface). Note that the OMERO web application does not seem to support being published at any other place than the server root ("/"). If your httpd server has another purposes beyong OMERO.web, you may want to use a VirtualHost; in that case, include the OMERO.web configuration inside a directive as follows: ---8<---------------------------------------------------------------- ServerName server.hostname ...insert the above-mentioned configuration stanza... --->8---------------------------------------------------------------- 6. BACKUP AND RESTORE There are three different items to backup: - configuration settings in /etc/omero/; - the data directory (/OMERO by default, see 4. above); - the PostgreSQL database. The following commands backup everything into /backup: $ pg_dump -h localhost -U postgres -C omero > /backup/omero.sql $ rsync --archive --delete --compress --prune-empty-dirs \ /OMERO /backup/omero.data To restore, copy the configuration and data files back to their locations and reload the database from the SQL dump. 7. UPGRADE For general informations about upgrading OMERO, see: http://www.openmicroscopy.org/site/support/omero5/sysadmins/server-upgrade.html To upgrade OMERO 4.4.x to OMERO-5.0.0: - stop OMERO if it is running; - backup the SQL database; - upgrade the package; - upgrade the database: $ cd /opt/omero $ psql -h localhost -U omero omero < sql/psql/OMERO5.0__0/OMERO4.4__0.sql - check config files in /etc/omero; remove old config file /etc/omero/grid/default.xml and apply new settings: # /etc/rc.d/rc.omero init - start the upgraded server: # /etc/rc.d/rc.omero start