OMERO.server installation
=========================
.. seealso::
:doc:`/sysadmins/server-upgrade`
Instructions for **upgrading** your OMERO.server installation.
:doc:`server-install-homebrew`
Instructions for installing your OMERO.server on Mac OS X using Homebrew.
:doc:`server-install-linux`
Instructions for installing your OMERO.server on Debian/Ubuntu.
:snapshot:`OMERO Installation for Mac OS X Snow Leopard (10.6) <omero/osx/Omero-MacInstalltionGuide-ver214.pdf>`
A guide provided by Janek Claus and Kenneth Arcieri (NIH/NICHD/UCSS)
for users wishing to install OMERO 4.1 on Mac OS 10.6, including
details on how to build all dependencies from source. The OMERO 4.4
and 4.3 installs are almost identical to 4.2 and 4.1 (except for web
client), so this guide will still be useful.
:snapshot:`Omero Server Beta 4.2.0 installation on CentOS <omero/linux/OMERO-Server-4-2-0-Installation-CentOS.pdf>`
A guide provided by Caterina Strambio De Castillia and Vanni
Galli (University of Geneva/SUPSI in Lugano) for users wishing
to install OMERO 4.1.1 or 4.2.0 on CentOS.
Limitations
-----------
Installation **will require a "root" level account** for which you
know the password. If you are unsure of what it means to have a "root"
level account, or if you are generally having issues with the various
users/passwords described in this install guide, please see
:ref:`troubleshooting-password`.
Prerequisites
-------------
.. note:: The installation of these prerequisite applications is outside the scope of this document. For Linux distributions you should use the default package manager.
The following are necessary:
Java SE Development Kit (JDK) (1.6 or higher)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Java SE Downloads are available from `<http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_
UNIX systems, you can check which version of Java is
currently available to you via your $PATH as follows:
::
$ which java
/usr/bin/java
$ java -version
java version "1.6.0"
Java(TM) SE Runtime Environment (build 1.6.0-b105)
Java HotSpot(TM) Server VM (build 1.6.0-b105, mixed mode)
Further, you can see if you have the Java compiler (Java SDK)
installed and available via your $PATH as follows…
::
$ which javac
/usr/bin/javac
$ javac -version
javac 1.6.0
Python 2 (2.6 or later)
^^^^^^^^^^^^^^^^^^^^^^^
Check you have Python (and what version) by typing:
::
$ python --version
Python 2.7.5+
OMERO does not currently support Python 3.
The following are optional depending on what services you require:
.. tabularcolumns:: |l|l|l|
.. list-table::
:header-rows: 1
* - Package
- Functionality
- Downloads
* - `Pillow`_ [1]_
- OMERO.web and Figure Export
- `Pillow page <https://pypi.python.org/pypi/Pillow>`_
* - Matplotlib_
- OMERO.web
- `Matplotlib page <http://matplotlib.org/>`_
* - NumPy (1.2.0 or higher) [2]_
- Scripting
- `Numpy/Scipy page <http://www.scipy.org/Download>`_
* - PyTables (2.1.0 or higher)
- :doc:`OMERO.tables </sysadmins/server-tables>`
- `PyTables page <http://www.pytables.org/moin/Downloads>`_
* - scipy.ndimage
- :omero_plone:`Volume Viewer <volume-viewer-in-omero.web>` [3]_
- `Numpy/Scipy page <http://www.scipy.org/Download>`_
.. [1] Make sure to have `libjpeg <http://libjpeg.sourceforge.net/>`_ installed when building `Pillow`_.
.. [2] May already have been installed as a dependency of Matplot Lib.
.. [3] Allows larger volumes to be viewed in the :omero_plone:`Volume Viewer <volume-viewer-in-omero.web>`.
Ice (3.3.x or 3.4.x)
^^^^^^^^^^^^^^^^^^^^
.. note::
OMERO |version| supports Ice3.4, but this requires the correct
version of OMERO.server (see :downloads:`Downloads
<>`). See :faq_plone:`"Do I use Ice 3.3 or
Ice 3.4?" <omero/do-i-use-ice-3.3-or-ice-3.4>` in
the FAQ. If you have further questions, consult the :forum:`Forums <>`.
UNIX source downloads and binary packages are available from ZeroC_.
The latest compatible distribution is the :zeroc:`3.3.1 release
<download_3_3_1.html>`. ZeroC does not provide binaries which work out of the
box for Mac OS X Snow Leopard (10.6), so we recommend you follow the
instructions for installation using :doc:`Homebrew <server-install-homebrew>`
instead if this is your OS.
PostgreSQL (8.4 or higher)
^^^^^^^^^^^^^^^^^^^^^^^^^^
PostgreSQL installed and configured with PL/pgSQL and to accept TCP
connections. PostgreSQL 8.3 and earlier are not supported. See
:doc:`server-postgresql` for specifics about each version.
OMERO.server
^^^^^^^^^^^^
The :file:`OMERO.server.zip` is available from the :downloads:`OMERO downloads
<>` page.
Environment variables
---------------------
For the prerequisite software to run properly, your PATH, PYTHONPATH,
and (DY)LD\_LIBRARY\_PATH environment variables must be configured. If
you installed via a package manager such as rpm, apt-get, or macports,
they should be set for you. If not correctly configured or if you
installed manually to /opt/Ice-… or a similar location, you will need
to set the values yourself.
If you are running a Linux distribution such as Debian or Ubuntu and
have used APT to install the prerequisites then the installed software
will have been installed to locations in your file system according to
the Debian Policy Manual for software packaging. You can explicitly set
your environment variables to reflect these install locations by editing
the .bashrc (if on Linux) or .profile (if on Mac OS X) file which can be
found within your home directory. For example, as of writing, on Debian
and Ubuntu the following environment variables should be set:
::
export JAVA_HOME=/usr/lib/jvm/java-6-sun
export JRE_HOME=/usr/lib/jvm/java-6-sun
export ICE_HOME=/usr/share/Ice-3.3.1
export POSTGRES_HOME=/usr/lib/postgresql/8.4
export PYTHONPATH=/usr/lib/pymodules/python2.6:$PYTHONPATH
export DYLD_LIBRARY_PATH=/usr/share/java:/usr/lib/:$DYLD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/share/java:/usr/lib:$LD_LIBRARY_PATH
export PATH=$PATH:$JAVA_HOME/bin:$JRE_HOME/bin:$ICE_HOME/bin:$POSTGRES_HOME/bin
Please note that the precise details of these environment variables can
change as new versions of software are released. You can retrieve the
pathname for a file by using the which command. So if you are unsure
what path to use in your environment variables, e.g. for the ICE\_HOME
variable you can execute the following command:
::
$ which icegridnode
/Users/ome/apps/OMERO.libs/bin/icegridnode
You can now set the ICE\_HOME path to something similar to
**/Users/ome/apps/OMERO.libs/bin** based upon the output from which,
e.g.
::
export ICE_HOME=/Users/ome/apps/OMERO.libs/bin/icegridnode
As a last ditch effort, on a Linux or Mac OS X machine you can use the
find command to help you discover whereabouts something is located in
your filesystem. e.g.
::
$ find / -name "icegridnode" 2>/dev/null
However this might take a long time to run, especially on a big
filesystem, so you might get a more timely solution by going to the
OMERO forums.
If the command gives no output then perhaps Ice is not installed, in
which case you should see the section above on installing Ice.
You can also add your OMERO bin directory to your path like so:
::
export PATH=$PATH:path-to-your-omero-install-directory/bin
When performing some operations the clients make use of temporary file
storage and log directories. By default these files are stored below the
users HOME directory in ``$HOME/omero/tmp``, ``$HOME/omero/log`` and
``$HOME/omero/sessions`` (resp. ``$HOME\omero\tmp``, ``$HOME\omero\log`` and
``$HOME\omero\sessions``). If your home(\ ``~``) directory ``$HOME`` is
stored on a network, possibly NFS mounted (or similar), then these
temporary files are being written and read over the network. This can
slow access down.
The OMERO.server also access the ``$HOME/omero/tmp`` and
``$HOME/omero/log`` folders of **the user the server process is running
as** (resp. ``$HOME\omero\tmp`` and ``$HOME\omero\log``).
As the server makes heavier use of these folders than the clients,
if the users home(\ ``~``) is stored on a network the server can be
slowed down. To get round this for the OMERO.server you can define an
``OMERO_TEMPDIR`` environment variable pointing to a temporary directory
located on the local file system e.g. ``/tmp`` (resp. ``C:\tmp\``).
Creating a database as root
---------------------------
Probably the most important step towards having a working server system
is having a properly configured database.
On most systems, a "postgres" user will be created which has admin
privileges, while the UNIX ``root`` user itself does *not* have admin
privileges. Therefore it is necessary to either become the ``postgres``
user or use sudo as below:
- Create a non-superuser database user and record the name and password. You
will need to configure OMERO to use your username and password by setting
the omero.db.name and omero.db.pass properties (below).
::
# For PostgreSQL 8.4.x and later
$ sudo -u postgres createuser -P -D -R -S db_user
Enter password for new role: # db_password
Enter it again: # db_password
.. warning::
For illustrative purposes, the default name and password for the user
are ``db_user`` and ``db_password`` respectively. However, you
should not use these default values for your installation but use
your own choice of username and password instead.
- Create a database for OMERO to reside in
::
$ sudo -u postgres createdb -O db_user omero_database
- Add the PL/pgSQL language to your database
::
$ sudo -u postgres createlang plpgsql omero_database
- Check to make sure the database has been created, you have PostgreSQL
client authentication correctly set up and the database is owned by
the **db\_user** user.
::
$ psql -h localhost -U db_user -l
Password for user db_user:
List of databases
Name | Owner | Encoding
----------------+----------+-----------
omero_database | db_user | UTF8
postgres | postgres | UTF8
template0 | postgres | UTF8
template1 | postgres | UTF8
(4 rows)
If you have problems, especially with the last step, take a look at
:doc:`server-postgresql` since the authentication mechanism
is probably not properly configured.
Location for the your OMERO binary repository
---------------------------------------------
- Create a directory for the OMERO binary data repository. ``/OMERO`` (resp. ``C:\OMERO``)
is the default location and should be used unless you explicitly have
a reason not to and know what you are doing.
- This is *not* where you want the OMERO application to be installed,
it is a *separate* directory that OMERO.server will use to store
binary data:
- You can read more about the :doc:`OMERO binary repository <server-binary-repository>`.
::
$ sudo mkdir /OMERO
- Change the ownership of the directory. ``/OMERO`` \*\ *must* either
be owned by the user starting the server (it is currently owned by
the system root) or that user **must** have permission to write to
the directory. You can find out your username and edit the correct
permissions as follows:
::
$ whoami
ome
$ sudo chown -R ome /OMERO
Installation
------------
- Extract the OMERO tarball and note its location. Below it is referred
to as: ``~/Desktop/omero``
- Optionally, review ``~/Desktop/omero/etc/omero.properties`` which
contains all default settings.
You will need to open the file with a text editor. Do not edit the file.
Any configuration settings you would like to change can be changed in the
next step.
- Change any settings that are necessary using :omerocmd:`config`,
including the name and/or password for the 'db\_user' database user
you chose above or the database name if it is not "omero\_database".
(Quotes are only necessary if the value could be misinterpreted by
the shell. See :forum:`link <viewtopic.php?f=5&t=360#p922>`)
::
$ cd ~/Desktop/omero
$ bin/omero config set omero.db.name 'omero_database'
$ bin/omero config set omero.db.user 'db_user'
$ bin/omero config set omero.db.pass 'db_password'
- If you have chosen a non-standard :doc:`OMERO binary repository <server-binary-repository>`
location above, be sure to configure the ``omero.data.dir`` property.
- Create the OMERO database initialization script. You will be asked
for the version of the script which you would like to generate, where
both defaults can be accepted. Finally, you will be asked to enter and
confirm password for your newly created OMERO root user.
.. warning::
For illustrative purposes, the default password for the OMERO rootuser
is ``root_password``. However, you should not use this default value
for your installation but use your own choice of password instead.
This should **not** be the same password as your Linux/Mac/Windows
root user!
.. parsed-literal::
$ cd ~/Desktop/omero
$ bin/omero db script
Please enter omero.db.version [OMERO\ |version|\ ]:
Please enter omero.db.patch [0]:
Please enter password for new OMERO root user: # root_password
Please re-enter password for new OMERO root user: # root_password
Saving to ~/Desktop/omero/OMERO\ |version|\ __0.sql
- Initialize your database with the script.
.. parsed-literal::
$ psql -h localhost -U db_user omero_database < OMERO\ |version|\ __0.sql
- Before starting the OMERO.server we should run the OMERO diagnostics
script so that we check that all of our settings are correct, e.g.
::
$ bin/omero admin diagnostics
- You can now start the server using:
::
$ bin/omero admin start
Creating var/master
Initializing var/log
Creating var/registry
No descriptor given. Using etc/grid/default.xml
- If you would like to move the directory again, see
``bin\winconfig.bat --help``, which gets called automatically on an
initial install.
- You can now test that you can log-in as "root", either with the
OMERO.insight client or command-line:
::
$ bin/omero login
Server: [localhost]
Username: [root]
Password: # root_password
JVM memory settings
-------------------
To make your server production-ready, you will likely need to increase the JVM
memory settings of your application descriptors. This is not done by default
since it would prevent starting the server on some sites' test instance but
for production use a setting higher than 512MB is **highly** recommended.
To increase the JVM memory settings, you need to edit the
:file:`etc/grid/templates.xml` file under the OMERO.server directory.
It is highly recommended to increase the ``BlitzTemplate`` default JVM memory
settings from ``-Xmx512M`` to ``-Xmx2048M`` and from ``XX:MaxPermSize=128m``
to ``XX:MaxPermSize=256M`` in production.
If working with large images generates ``OutOfMemory`` exceptions in the
:file:`var/log/PixelData-0.log` file, you may consider increasing the
``PixelDataTemplate`` default JVM memory settings to ``-Xmx1024M``.
Once you have modified the :file:`templates.xml` file, restart the server
using::
$ bin/omero admin restart
.. seealso::
http://www.openmicroscopy.org/community/viewtopic.php?f=4&t=7400
Forum thread on PixelData JVM memory settings
:ref:`gridconfiguration`
Section of the advanced server configuration documentation describing
:file:`etc/grid/templates.xml`.
OMERO.web and administration
----------------------------
.. note:: In order to deploy OMERO.web in a production environment such as Apache or IIS please follow the instructions under :doc:`install-web`.
Otherwise, the internal Django webserver can be used for evaluation and development. In this case, we need to
turn debugging on, in order that static files can be served by Django:
::
$ bin/omero config set omero.web.application_server development
$ bin/omero config set omero.web.debug True
then start by
::
$ bin/omero web start
Starting django development webserver...
Validating models...
0 errors found
Django version 1.1.1, using settings 'omeroweb.settings'
Development server is running at http://0.0.0.0:4080/
Quit the server with CONTROL-C.
Once you have deployed and started the server you can use your browser
to access the OMERO.web interface:
- `http://localhost:4080/ <http://localhost:4080/>`_
.. figure:: /images/installation-images/login.png
:align: center
:width: 55%
:alt: OMERO.webadmin login
OMERO.webadmin login
Enabling movie creation from OMERO.
-----------------------------------
OMERO has the facility to create AVI/MPEG Movies from Images, which can
be called from OMERO.insight. The page :doc:`/sysadmins/omeromovie` gives details on how to enable them.
Post-installation items
-----------------------
Backup
^^^^^^
One of your first steps after putting your OMERO server into production
should be deciding on when and how you are going to :doc:`backup your
database and binary data </sysadmins/server-backup-and-restore>`. Please do not omit this
step.
Security
^^^^^^^^
It is also now recommended that you read the :doc:`/sysadmins/server-security` page
to get a good idea as to what you need to do to get OMERO clients
speaking to your newly installed OMERO.server in accordance with your
institution or company's security policy.
Advanced configuration
^^^^^^^^^^^^^^^^^^^^^^
Once you have the base server running, you may want to try enabling some
of the advanced features such as :doc:`/sysadmins/dropbox` or :doc:`/sysadmins/server-ldap`.
If you have ***Flex data***, you may want to watch :snapshot:`the HCS configuration screencast <movies/omero-4-1/mov/FlexPreview4.1-configuration.mov>`.
See the :omero_plone:`Feature list <feature-list>` for more advanced
features you may want to use, and :doc:`/sysadmins/server-advanced-configuration` on how to get the most out of
your server.
Update notification
^^^^^^^^^^^^^^^^^^^
Your OMERO.server installation will check for updates each time it is started from the *Open Microscopy Environment* update server. If you wish to disable this functionality you should do so now as outlined on the :doc:`/sysadmins/UpgradeCheck` page.
Troubleshooting
^^^^^^^^^^^^^^^
My OMERO install doesn't work! What do I do now? Examine the :doc:`/sysadmins/troubleshooting` page and if all else fails post a
message to our :mailinglist:`ome-users` mailing list discussed on the :doc:`/users/community-resources` page.
OMERO diagnostics
^^^^^^^^^^^^^^^^^
If you want help with your server installation, please include the output of the diagnostics command:
.. parsed-literal::
$ bin/omero admin diagnostics
================================================================================
OMERO Diagnostics |release|
================================================================================
Commands: java -version 1.6.0 (/usr/bin/java)
Commands: python -V 2.6.5 (/usr/bin/python)
Commands: icegridnode --version 3.3.1 (/usr/bin/icegridnode)
Commands: icegridadmin --version 3.3.1 (/usr/bin/icegridadmin)
Commands: psql --version 8.4.12 (/usr/bin/psql)
Server: icegridnode running
Server: Blitz-0 active (pid = 28933, enabled)
Server: DropBox active (pid = 28951, enabled)
Server: FileServer active (pid = 28954, enabled)
Server: Indexer-0 active (pid = 28957, enabled)
Server: MonitorServer active (pid = 28960, enabled)
Server: OMERO.Glacier2 active (pid = 28962, enabled)
Server: OMERO.IceStorm active (pid = 28964, enabled)
Server: PixelData-0 active (pid = 28963, enabled)
Server: Processor-0 active (pid = 28972, enabled)
Server: Tables-0 active (pid = 28974, enabled)
Server: TestDropBox inactive (enabled)
Log dir: /home/omero/OMERO.server-|version|
Log files: Blitz-0.log 360.0 MB errors=9 warnings=2458
Log files: DropBox.log 3.0 KB errors=0 warnings=1
Log files: FileServer.log 0.0 KB
Log files: Indexer-0.log 506.0 KB errors=0 warnings=90
Log files: MonitorServer.log 2.0 KB
Log files: OMEROweb.log 710.0 KB errors=5 warnings=2
Log files: OMEROweb.log.1 777.0 KB errors=0 warnings=1
Log files: OMEROweb.log.2 776.0 KB errors=0 warnings=2
Log files: OMEROweb.log.3 777.0 KB
Log files: OMEROweb.log.4 879.0 KB errors=1 warnings=2
Log files: OMEROweb.log.5 258.0 KB
Log files: OMEROweb_request.log 10.0 KB errors=3 warnings=3
Log files: PixelData-0.log 4.0 KB
Log files: Processor-0.log 315.0 KB errors=0 warnings=1
Log files: Tables-0.log 2.0 KB errors=0 warnings=1
Log files: TestDropBox.log n/a
Log files: master.err 0.0 KB
Log files: master.out 0.0 KB
Log files: Total size 365.49 MB
Parsing Blitz-0.log:[line:30] => Server restarted <=
Parsing Blitz-0.log:[line:213] => Server restarted <=
Environment:OMERO_HOME=(unset)
Environment:OMERO_NODE=(unset)
Environment:OMERO_MASTER=(unset)
Environment:PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
Environment:ICE_HOME=(unset)
Environment:LD_LIBRARY_PATH=(unset)
Environment:DYLD_LIBRARY_PATH=(unset)
OMERO data dir: '/OMERO' Exists? True Is writable? True
OMERO.web status... [RUNNING] (PID 28736)