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 `_ 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 `_. 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 `_ 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 `_. 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 `_. 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.