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) ` 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 ` 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 ``_ 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.4 or higher) ^^^^^^^^^^^^^^^^^^^^^^^^ Check you have Python (and what version) by typing: :: $ python --version Python 2.5.1 OMERO does not 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 * - `Python Imaging Library`_ [1]_ - OMERO.web and Figure Export - `PIL page `_ * - Matplotlib_ - OMERO.web - `Matplotlib page `_ * - NumPy (1.2.0 or higher) [2]_ - Scripting - `Numpy/Scipy page `_ * - PyTables (2.1.0 or higher) - :doc:`OMERO.tables ` - `PyTables page `_ * - scipy.ndimage - :omero_plone:`Volume Viewer ` [3]_ - `Numpy/Scipy page `_ .. [1] Make sure to have `libjpeg `_ installed when building the `Python Imaging Library`_. .. [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 `. 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?" ` 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 `. 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 ` 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 `. :: $ 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 `) :: $ 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 ` 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 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/ `_ .. 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 `. 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 `. See the :omero_plone:`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. JVM memory settings """"""""""""""""""" The most likely change you will need to make to your application descriptors is increasing the memory settings. 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. You can either edit the file manually, or use a small script such as: :: perl -i -pe 's/Xmx512M/Xmx2048M/' etc/grid/templates.xml perl -i -pe 's/XX:MaxPermSize=128m/XX:MaxPermSize=256M/' etc/grid/templates.xml See the grid configuration section in the :doc:`Advanced server configuration ` documentation for more information on `grid/templates.xml`. 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)