OMERO.server binary repository
==============================

.. topic:: About

    The OMERO.server binary data repository is a fundamental piece of   
    server-side functionality. It provides optimized and indexed storage of
    original file, pixel and thumbnail data, attachments and full text 
    indexes. Its structure is based on :legacy_plone:`OMEIS <ome-server/system-overview/ome-image-server/>`.

Layout
------

The repository is internally laid out as follows:

::

    /OMERO
    /OMERO/Pixels      <--- Pixel data
    /OMERO/Files       <--- Original file data
    /OMERO/Thumbnails  <--- Thumbnail data
    /OMERO/FullText    <--- Lucene full text search index

**Your repository is not:**

-  the "database"
-  the directory where your OMERO.server binaries are
-  the directory where your OMERO.client (OMERO.insight, OMERO.editor or
   OMERO.importer) binaries are
-  your PostgreSQL data directory

Locking and remote shares
-------------------------

The OMERO server requires proper locking semantics on all files in the binary
repository. In practice, this means that remotely mounted shares such as AFS,
CIFS, and NFS can cause issues. If you have experience and/or the time to
manage and monitor the locking implementations of your remote filesystem, then
using them as for your binary repository should be fine.

If, however, you are seeing errors such as NullPointerExceptions, "Bad file
descriptors" and similar in your server log, then you will need to use
directly connected disks.

.. Warning::

    If your binary repository is a remote share and mounting the share fails
    or is dismounted, OMERO will continue operating using the mount point
    instead! To prevent this, make the mount point read-only for the OMERO
    user so that no data can be written to the mount point.

Changing your repository location
---------------------------------

.. note::

    It is **strongly** recommended that you make all changes to your OMERO
    binary repository with the server shut down. Changing the
    ``omero.data.dir`` configuration does **not** move the repository for you,
    you must do this yourself.

Your repository location can be changed from its ``/OMERO`` default by 
modifying your OMERO.server configuration as follows:

::

    $ cd OMERO.server
    $ bin/omero config set omero.data.dir /mnt/really_big_disk/OMERO

The suggested procedure is to shut down your OMERO.server instance, move
your repository, change your ``omero.data.dir`` and then start the
instance back up. For example:

::

    $ cd OMERO.server
    $ bin/omero admin stop
    $ mv /OMERO /mnt/really_big_disk
    $ bin/omero config set omero.data.dir /mnt/really_big_disk/OMERO
    $ bin/omero admin start

Permissions
-----------

Your repository should be owned by the same user that is starting your
OMERO.server instance. This is often either yourself (find this out by
executing ``whoami``) or a separate ``omero`` (or similar) user who is
dedicated to running OMERO.server. For example:

::

    $ whoami
    omero
    $ ls -al /OMERO
    total 24
    drwxr-xr-x  5 omero  omero   128 Dec 12  2006 .
    drwxr-xr-x  7 root    root   160 Nov  5 15:24 ..
    drwxr-xr-x  2 omero  omero  1656 Dec 18 14:31 Files
    drwxr-xr-x 25 omero  omero 23256 Dec 10 19:06 Pixels
    drwxr-xr-x  2 omero  omero    48 Dec  8  2006 Thumbnails