OMERO.server Mac OS X installation walk-through with Homebrew
=============================================================


.. topic:: Overview

    This walk-through demonstrates how to install OMERO on a clean Mac
    OS X system (10.8 or later) using Homebrew.  Note that this
    demonstrates how to install OMERO.server *from the source code*
    via Homebrew, in addition to all its prerequisites. **The default
    instructions for UNIX platforms in the**
    :doc:`server-installation` **guide are all you need to install the
    prerequisites with Homebrew and then install the server zip from
    the downloads page or build from source.**

These instructions are implemented in a series of `automated scripts
<https://github.com/ome/omero-install/tree/master/homebrew>`_ which
install OMERO via Homebrew from a fresh configuration.

Prerequisites
-------------

Xcode
^^^^^

Homebrew requires the latest version of Xcode.

- Install :program:`Xcode` from the App Store; if you have already
  installed it, make sure all the latest updates are installed

- Run the following command to install the command-line tools for Xcode::

    xcode-select --install

Java
^^^^

Oracle Java may be downloaded from the `Oracle website
<http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_.

After installing JDK 7 or JDK 8, check your installation works by
running::

    $ java -version
    java version "1.8.0_31"
    Java(TM) SE Runtime Environment (build 1.8.0_31-b13)
    Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)
    
    $ javac -version
    javac 1.8.0_31

Homebrew
^^^^^^^^

.. _`Homebrew wiki`: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Installation.md

Follow the installation instructions on the `Homebrew wiki`_. All the
requirements for OMERO will be installed under :file:`/usr/local`.

::

    $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    $ brew install git

The installation of OMERO via Homebrew depends upon two alternate
repositories containing extra formulae:
https://github.com/Homebrew/homebrew-science for the HDF5 formula and
https://github.com/ome/homebrew-alt for all the OME-provided formulae
and older versions of Ice.  To add these, run::

    $ brew tap homebrew/science
    $ brew tap ome/alt

Lastly, make sure :file:`/usr/local/bin` is before :file:`/usr/bin` in
your :envvar:`PATH`.  For example, add the following to
:file:`~/.profile` and then start a new shell for the change to take
effect::

    export PATH=/usr/local/bin:/usr/local/sbin:$PATH

Python 2.7
^^^^^^^^^^

.. _`Homebrew and Python`: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Homebrew-and-Python.md

You can install OMERO using either the Python 2.7 provided by
Homebrew, or the system-wide Python 2.7 provided by MacOS X. Homebrew
Python is recommended since it makes using Homebrew-provided modules
simpler, for example the Ice python bindings needed by OMERO. For a
more thorough description of the Homebrew solution, see the `Homebrew
and Python`_ page. Note that the automated script linked above tests
the OMERO installation using the Homebrew Python.

To install the Python provided by Homebrew::

	$ brew install python

Check that Python is working and is version 2.7::

    $ /usr/local/bin/python --version
    Python 2.7.9

If using system Python, add the following to :file:`~/.profile` and
then start a new shell for the change to take effect::

    export PYTHONPATH=$(brew --prefix omero)/lib/python

If using Homebrew Python, this will be on the default module path.

.. note::

    If you have a local :file:`.bash_profile` file, it will override
    your :file:`.profile` configuration file.


Independently of the chosen Python, you can set up and use `virtual
environments <http://www.virtualenv.org/en/latest/>`_ to install the OMERO
Python dependencies (see :ref:`python_dependencies`).

.. note::

    The Homebrew formulae used below provide Python bindings. As
    described in `Homebrew and Python`_, you should **not** be in an
    active virtual environment when you ``brew install`` them.


OMERO installation
------------------

OMERO |release|
^^^^^^^^^^^^^^^

To install and deploy the |release| release of OMERO.server, run::

    $ brew install omero

This should install OMERO along with most of the non-Python
requirements.

Additional installation options can be listed using the ``info``
command::

    $ brew info omero

The default version of Ice installed by the OMERO formula is currently
Ice 3.5.


Development server
^^^^^^^^^^^^^^^^^^

If you wish to build OMERO.server from source for development
purposes, using the git repository, first use Homebrew to install the
OMERO dependencies::

    $ brew install --only-dependencies omero

The default version of Ice installed by the OMERO formula is currently
Ice 3.5.

Prepare a place for your OMERO code to live, e.g.

::

    $ mkdir -p ~/code/projects/OMERO
    $ cd ~/code/projects/OMERO

If you installed Ice 3.5, you will need to set :envvar:`SLICEPATH` to be
able to build the server, i.e.
``export SLICEPATH=/usr/local/share/Ice-3.5/slice``.

.. include:: development-server

Additional OMERO requirements
-----------------------------

PostgreSQL
^^^^^^^^^^

Install PostgreSQL::

    $ brew install postgresql
    $ postgres --version
    postgres (PostgreSQL) 9.4.1

.. _python_dependencies:

Python dependencies
^^^^^^^^^^^^^^^^^^^

The Python dependencies can be installed in the system-wide Python
:file:`site-packages`, in the Homebrew Python :file:`site-packages` or
within a virtual environment. If you are using the system-wide Python
:file:`site-packages`, you may need to use :program:`sudo` to install
the dependencies. If you are using a virtual environment, activate it
before calling the Python dependencies installation script.

If you installed OMERO using Homebrew, execute the ``omero_python_deps``
script::

    $ omero_python_deps

If you use a development server, execute the ``python_deps.sh`` script under
:file:`docs/install`::

    $ cd ~/code/projects/OMERO
    $ docs/install/python_deps.sh

If you encounter problems with the installation script, please take a look at
:ref:`install_homebrew_common_issues`.

Configuration
-------------

Database creation
^^^^^^^^^^^^^^^^^

#. Create a new database cluster::

    $ initdb -E UTF8 /usr/local/var/postgres

#. Start the PostgreSQL server.

   If you wish to use ``brew services`` to start postgresql, you will
   first need to install it, then start the service::

    $ brew tap gapple/services
    $ brew services start postgresql

   Alternatively, to start by hand::

    $ pg_ctl -D /usr/local/var/postgres/ -l /usr/local/var/postgres/server.log start

   It is also possible to configure :program:`launchd` to start
   PostgreSQL at boot

#. Create a user and database::

    $ createuser -P -D -R -S db_user
    Enter password for new role:       # enter db_password
    Enter it again:                    # enter db_password
    $ createdb -E UTF8 -O db_user omero_database

   Note ``db_user`` and ``db_password`` should be replaced with a
   username and password of your choice.  Record these for future use.

#. Check to make sure the database has been created.

::

    $ psql -h localhost -U db_user -l

This command should give similar output to the following::

                            List of databases

       Name         | Owner   | Encoding |  Collation  |    Ctype    | Access privileges
    ----------------+---------+----------+-------------+-------------+-------------------
     omero_database | db_user | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
     postgres       | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 |
     template0      | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/ome           +
                    |         |          |             |             | ome=CTc/ome
     template1      | ome     | UTF8     | en_GB.UTF-8 | en_GB.UTF-8 | =c/ome           +
                    |         |          |             |             | ome=CTc/ome
    (4 rows)

OMERO.server
^^^^^^^^^^^^

Now configure OMERO.server to connect to the newly-created database::

    $ omero config set omero.db.name omero_database
    $ omero config set omero.db.user db_user
    $ omero config set omero.db.pass db_password

And then, generate the database schema::

    $ omero db script --password secretpassword

You should see output similar to this:

.. literalinclude:: /downloads/cli/db-script-example.txt

Then run the SQL commands in the generated schema file to create the
database:

.. parsed-literal::

    $ psql -h localhost -U db_user omero_database < |current_dbver|.sql

Now create a location to store OMERO data, for example::

    $ mkdir -p ~/var/OMERO.data

and configure OMERO.server to use this location::

    $ omero config set omero.data.dir ~/var/OMERO.data

The OMERO.server configuration settings can be inspected using::

    $ omero config get

Next, start the OMERO.server::

    $ omero admin start

Now connect to your OMERO.server using OMERO.insight with the following credentials:

::

    U: root
    P: root_password

OMERO.web
^^^^^^^^^

In order to deploy OMERO.web in a production environment such as Apache or
Nginx please follow the instructions under :doc:`install-web`.

.. note::
    The internal Django webserver can be used for evaluation and development.
    In this case please follow the instructions under
    :doc:`/developers/Web/Deployment`.

.. _install_homebrew_common_issues:

Common issues
-------------

General considerations
^^^^^^^^^^^^^^^^^^^^^^

If you run into problems with Homebrew, you can always run::

    $ brew update
    $ brew doctor

Also, please check the Homebrew `Bug Fixing Checklist
<https://github.com/mxcl/homebrew/wiki/Bug-Fixing-Checklist>`_.

Below is a non-exhaustive list of errors/warnings specific to the OMERO
installation. Some if not all of them could possibly be avoided by removing
any previous OMERO installation artifacts from your system.

Macports/Fink
^^^^^^^^^^^^^

::

    Warning: It appears you have MacPorts or Fink installed.

Follow uninstall instructions from the `Macports guide <http://guide.macports.org/chunked/installing.macports.uninstalling.html>`_.

PostgreSQL
^^^^^^^^^^

If you encounter this error during installation of PostgreSQL::

    Error: You must ``brew link ossp-uuid' before postgresql can be installed

try::

    $ brew cleanup
    $ brew link ossp-uuid

szip
^^^^

If you encounter an MD5 mismatch error similar to this::

    ==> Installing hdf5 dependency: szip
    ==> Downloading http://www.hdfgroup.org/ftp/lib-external/szip/2.1/src/szip-2.1.tar.gz
    Already downloaded: /Library/Caches/Homebrew/szip-2.1.tar.gz
    Error: MD5 mismatch
    Expected: 902f831bcefb69c6b635374424acbead
    Got: 0d6a55bb7787f9ff8b9d608f23ef5be0
    Archive: /Library/Caches/Homebrew/szip-2.1.tar.gz
    (To retry an incomplete download, remove the file above.)

then manually remove the archived version located under
:file:`/Library/Caches/Homebrew`, since the maintainer may have
updated the file.

numexpr (and other Python packages)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you encounter an issue related to numexpr complaining about NumPy
having too low a version number, verify that you have not previously
installed any Python packages using :program:`pip`. In the case where
:program:`pip` has been installed before Homebrew, uninstall it::

    $ sudo pip uninstall pip

and then try running :file:`python_deps.sh` again. That should install
:program:`pip` via Homebrew and put the Python packages in correct
locations.