OMERO.server installation on OS X with Homebrew =============================================== .. topic:: Overview This walkthrough demonstrates how to install OMERO on a clean Mac OS X system (10.9 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. It is aimed at **developers** since typically MacOS X is not suited for serious server deployment. 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` and the Command Line Tools for Xcode from the App Store. If you have already installed it, make sure all the latest updates are installed. 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_51" Java(TM) SE Runtime Environment (build 1.8.0_51-b16) Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode) $ javac -version javac 1.8.0_51 Requirements ------------ .. _`Homebrew wiki`: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Installation.md All the requirements for OMERO will be installed under :file:`/usr/local`. See also: Installation instructions on the `Homebrew wiki`_. Install Homebrew and make sure :file:`/usr/local/bin` is prepended to your :envvar:`PATH`:: $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" $ export PATH=/usr/local/bin:$PATH Update Homebrew and run 'brew doctor' to fix potential issues beforehand:: $ brew update $ brew doctor Install git if not already present:: $ brew list | grep "\bgit\b" || brew install git Install PostgreSQL database server:: $ export LANG=${LANG:-en_US.UTF-8} $ export LANGUAGE=${LANGUAGE:-en_US:en} $ brew install postgresql .. _`Homebrew and Python`: https://github.com/Homebrew/homebrew/blob/master/share/doc/homebrew/Homebrew-and-Python.md You should install OMERO using Python 2.7 provided by Homebrew 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:: $ which python /usr/local/bin/python $ python --version Python 2.7.9 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 .. 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. See the :download:`step01_deps.sh ` script for the steps described above. OMERO installation ------------------ OMERO |release| server ^^^^^^^^^^^^^^^^^^^^^^ To install and deploy the |release| release of OMERO.server, run:: $ brew install omero53 --with-nginx --with-cpp $ export PYTHONPATH=$(brew --prefix omero53)/lib/python $ export ICE_CONFIG=$(brew --prefix omero53)/etc/ice.config This will install the OMERO server to /usr/local/Cellar/omero, which means you will find the log files in :file:`/usr/local/Cellar/omero/|release|/var/log`. The binaries will be linked to :file:`/usr/local/bin`:: $ which omero /usr/local/bin/omero Install Ice 3.6 extension for Python and OMERO python dependencies:: $ pip install -r $(brew --prefix omero53)/share/web/requirements-py27-all.txt $ cd /usr/local $ bash bin/omero_python_deps Start database server:: $ pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log -w start Create database and user:: $ createuser -w -D -R -S db_user $ createdb -E UTF8 -O db_user omero_database $ psql -h localhost -U db_user -l Set database parameters in OMERO:: $ omero config set omero.db.name omero_database $ omero config set omero.db.user db_user $ omero config set omero.db.pass db_password Create and run script to initialize the OMERO database:: $ export ROOT_PASSWORD=${ROOT_PASSWORD:-omero} $ omero db script --password $ROOT_PASSWORD -f - | psql -h localhost -U db_user omero_database Set up OMERO data directory:: $ export OMERO_DATA_DIR=${OMERO_DATA_DIR:-~/OMERO.data} $ mkdir -p $OMERO_DATA_DIR $ omero config set omero.data.dir $OMERO_DATA_DIR See the OMERO installation script :download:`step02_omero.sh ` 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.6. Prepare a place for your OMERO code to live, e.g.:: $ mkdir -p ~/code/projects $ cd ~/code/projects If you want the development version of OMERO.server, you can clone the source code from the project's GitHub account to build locally:: $ git clone --recursive git://github.com/openmicroscopy/openmicroscopy $ cd openmicroscopy && ./build.py .. note:: If you have a GitHub account and you plan to develop code for OMERO, you should make a fork into your own account and then clone this fork to your local development machine, e.g. :: $ git remote add git://github.com/YOURNAMEHERE/openmicroscopy $ cd openmicroscopy && ./build.py .. seealso:: :doc:`/developers/installation` Developer documentation page on how to check out to source code :doc:`/developers/build-system` Developer documentation page on how to build the OMERO.server Then prepend the development :file:`bin` directory to your :envvar:`PATH` to pick the right executbale:: $ export PATH=~/code/projects/openmicroscopy/dist/bin:$PATH and follow the steps for setting up the database and OMERO data directory as mentioned in the previous section. OMERO.web ^^^^^^^^^ Basic setup for OMERO using Nginx:: $ export HTTPPORT=${HTTPPORT:-8080} $ omero web config nginx-development --http $HTTPPORT > $(brew --prefix omero53)/etc/nginx.conf See installation script :download:`step03_nginx.sh ` For detailed instructions on how to deploy OMERO.web in a production environment such as Nginx please see :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: Startup/Shutdown ^^^^^^^^^^^^^^^^ If necessary start PostgreSQL database server:: $ pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log -w start Start OMERO:: $ omero admin start Start OMERO.web:: $ omero web start $ nginx -c $(brew --prefix omero53)/etc/nginx.conf Now connect to your OMERO.server using OMERO.insight or OMERO.web with the following credentials: :: U: root P: omero Stop OMERO.web:: $ nginx -c $(brew --prefix omero53)/etc/nginx.conf -s stop $ omero web stop Stop OMERO:: $ omero admin stop See example script for a basic functionality test: :download:`step04_test.sh ` 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. Database ^^^^^^^^ Check to make sure the database has been created and 'UTF8' encoding is used :: $ 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) 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 For recent versions of OS X (10.10 and above) some directories may be missing, preventing PostgreSQL from starting up. In that case, it should be sufficient to reinitialize a PostgreSQL database cluster as:: $ rm -rf /usr/local/var/postgres $ initdb -E UTF8 /usr/local/var/postgres .. seealso:: http://stackoverflow.com/questions/25970132/pg-tblspc-missing-after-installation-of-latest-version-of-os-x-yosemite-or-el 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.