slackbuilds/n/omero-server/README

                 PACKAGER'S README FOR OMERO-5.6.2

            Damien Goutte-Gattat <dgouttegattat@incenp.org>


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 <https://docs.openmicroscopy.org/omero/5.6.2/sysadmins/index.html>.


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 three 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' user's home directory, by default `/var/lib/omero'
      (as created by the `doinst.sh' script, see above); it will hold
      some temporary files;

    - the data repository, where OMERO will store the raw data files,
      `/OMERO' by default.

   The three locations must be readable and writable by the `omero' user.

   The main directory is hardcoded in the SlackBuild and the associated
   scripts, but not in OMERO itself; you may change it 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
   OMERO configuration.


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.*').

   All parameters may be set by running the `omero config` command under
   the `omero` account. For example, to set the directory of the data
   repository:

     $ omero config set omero.data.dir /data/omero

   Parameters may also be defined in a `/etc/omero.conf` files, using
   the same format as the `omero.properties` file provided with OMERO.

   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
   file `/etc/omero.conf` if it exists 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 the
   `/etc/omero.conf` is modified.


5. OMERO.web

   The Django-based web application OMERO.web is no longer packaged
   along with OMERO.server. Use the n/omero-web package to install it.

   Make sure Nginx and Django are installed. Add the following line to
   the OMERO configuration file /etc/omero.conf:

   ---8<----------------------------------------------------------------
   omero.web.application_server=wsgi
   --->8----------------------------------------------------------------

   Then, use the following command to produce a configuration snippet
   that can be directly inserted into the configuration of Nginx:

     omero web config nginx

   Start the web server, the OMERO server itself and the OMERO.web
   workers using the rc scripts provided in the corresponding packages.


6. BACKUP AND RESTORE

   There are two different items to backup:

    - 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 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 5.5.x to OMERO-5.6.2:

    - Make sure you have Python3, as OMERO-5.6.x no longer supports Python2;

    - stop OMERO if it is running;

    - backup the SQL database;

    - upgrade the package;

    - start the upgraded server:

        # /etc/rc.d/rc.omero start