Personal tools

You are here: Home → Support → OMERO Platform v4 → OMERO.server → Install
 

Install

OMERO.server Installation for UNIX Based Platforms (including Mac OS X)

  • If you are upgrading your OMERO.server installation you want to follow instructions on the upgrade page.
  • If you are attempting a Microsoft Windows install please see the Microsoft Windows install page.
  • Additional walkthoughs for Mac using MacPorts on Mac OS X 10.6 or manual downloads on Mac OS X 10.5 may be of use to less experienced users.

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 the section under "Troubleshooting".

Prerequisites

  • PostgreSQL 7.4 or higher installed and configured with PL/pgSQL and to accept TCP connections. See OMERO and PostreSQL for instructions. 8.4 has significantly increased security settings and can be difficult for beginners. We suggest using 8.3.

  • Java 1.5 SE Development Kit (JDK) or higher installed http://java.sun.com/javase/downloads/index.jsp 

    #!sh
# 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
    • On systems with OpenJDK installed by default, it will be necessary to unselect it and select the Sun version. See this thread for more information.

  • Ice 3.3.x installed

    UNIX source downloads and binary packages are available on the ZeroC download page.

  • Python 2.4.x or higher installed. If you are using Python 2.4, you will need pysqlite. Use version 2.0.3 or higher. Python 2.5 ships with an SQLite wrapper in the standard library, so you do not need to install anything extra in that case

  • Python Imaging Library (for OMERO.web only) Packages should be available for your distribution from here

  • Matplot Lib (for OMERO.web only) Packages should be available for your distribution from here

NOTE: The installation of these applications is outside the scope of this document but some additional notes for Mac can be found here.

Environment Variables

For the pre-requisite 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.

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. The default name and password for the user is "omero". If you choose other values, you will need to configure the omero.db.name and omero.db.pass values (below). 

    # For PostgreSQL 7.4.x
# sudo -u postgres createuser -W -D -A <db_username>
sudo -u postgres createuser -W -D -A omero

# For PostgreSQL 8.0.x
# sudo -u postgres createuser -P -D -A <db_username>
 sudo -u postgres createuser -P -D -A omero

# For PostgreSQL 8.1.x, 8.2.x, 8.3.x, 8.4.x
# sudo -u postgres createuser -P -D -R -S <db_username>
sudo -u postgres createuser -P -D -R -S omero

  • Create a database for OMERO to reside in 

    # sudo -u postgres createdb -O <db_username> <db_name>
sudo -u postgres createdb -O omero omero

  • Add the PL/pgSQL language to your database 

    # sudo -u postgres createlang plpgsql <db_name>
sudo -u postgres createlang plpgsql omero

  • Check to make sure the database has been created, you have PostgreSQL client authentication correctly set up and the database is owned by the omero user. 

    $ psql -h localhost -U omero -l
Password for user omero: 
        List of databases
   Name    |  Owner   | Encoding  
-----------+----------+-----------
 omero     | omero    | SQL_ASCII
 postgres  | postgres | SQL_ASCII
 template0 | postgres | SQL_ASCII
 template1 | postgres | SQL_ASCII
(4 rows)

If you have problems, especially with the last step, take a look at Omero and 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 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 seperate directory that OMERO.server will use to store binary data:

  • You can read more about there OMERO binary repository here. 

      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
callan
$ sudo chown -R callan /OMERO

Installation

  • Extract the OMERO tarball and note its location. Below it is referred to as: ~/Desktop/omero

  • Optionally, review ~/Desktop/etc/omero.properties which contains all default settings. You will need to open the file with a text editor. Don't 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 bin/omero config, including the name and/or password for the 'omero' database user you chose above or the database name if they are not "omero". 

        cd ~/Desktop/omero
    bin/omero config set omero.db.name myDatabase
    bin/omero config set omero.db.user me
    bin/omero config set omero.db.pass TopSecret

  • Alternative configuration: You can alternatively add any settings you'd like to modify to the "Profile" properties element in etc\grid\default.xml.

    For example, 

      properties id="Profile"
      property name="omero.db.name" value="myDatabase"
      property name="omero.db.user" value="me"
      property name="omero.db.pass" value="TopSecret"

  • If you have chosen a non-standard OmeroBinaryRepository 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'll be asked to enter and confirm password for your newly created OMERO root user (this should not be the same as your Linux/Mac root user!) 

    $ cd ~/Desktop/omero 
$ bin/omero db script
Please enter omero.db.version [OMERO4.1]: 
Please enter omero.db.patch [0]: 
Please enter password for new OMERO root user: 
Please re-enter password for new OMERO root user: 
Saving to ~/Desktop/omero/OMERO4.1__0.sql

  • Initialize your database with the script. 

    $ psql -h localhost -U omero omero < OMERO4.1__0.sql

  • Start the server: 

    $ bin/omero admin start
Creating var/master
Initializing var/log
Creating var/registry
No descriptor given. Using etc/grid/default.xml
$

OMERO.web and Administration

OMERO.web ships with OMERO.server and is started by default with the Django lightweight development Web server bound to port 8000 on 127.0.0.1 when you deploy your OMERO.server instance. A build-in web server written purely in Python is ideal for demonstrating/testing how powerful application is. Unfortunately, this server is only designed to run in a local environment and could not deal with the pressures of a production mode of the application used by many people concurrently. For that, you need to deploy OMERO.web to a production-grade web server, such as mod_python module for Apache. You can find more information on the Django site here.

Configuration Guide for mod_python (production mode) is available on the separated page. If you wish to run OMERO.web on demonstration server please continue.

Starting OMERO.web on the Django server

PYTHONPATH

(4.1.1 and newer) You do not need to configure your Python path anymore.

(4.1.0 only) You need to configure your Python path to include the location of the OMERO python libraries. 

$ export PYTHONPATH=$PYTHONPATH:~/Desktop/omero/lib/python/
$ echo $PYTHONPATH
/opt/local/share/ice/python:~/Desktop/omero/lib/python/:

Pre-configuration

It is necessary to start the OMERO server before starting OMERO.web configuration.

When you run the OMERO.web first time please configure the following options (in production environment please remember to run as apache_user: sudo -u apache_user):

  • (4.1.1 and newer):

    • Settings (optional field can be blank) 

      $ bin/omero web settings
You just installed OMERO, which means you didn't have settings configured in OMERO.web.
Please enter the domain you want to run OMERO.web on (http://www.domain.com:8000/):http://web.openmicroscopy.org.uk/
Please enter the Email address you want to send from (omero_admin@example.com): web@openmicroscopy.org.uk
Please enter the SMTP server host you want to send from (smtp.example.com): smtp.openmicroscopy.org.uk
Optional: please enter the SMTP server port (default 25): 
Optional: Please enter the SMTP server username: 
Optional: Password: 
Optional: TSL? (yes/no): 
Saved to ~/Desktop/omero/lib/python/omeroweb/custom_settings.py

Please enter Username for OMERO.web administrator: webadmin
Please enter Email address: webadmin@openmicroscopy.org.uk
Please enter password for OMERO.web administrator: 
Please re-enter password for OMERO.web administrator: 
Saved to ~/Desktop/omero/lib/python/omeroweb/initial_data.json

Database synchronization...
(...)
Creating table feedback_emailtemplate
Creating table webadmin_gateway
Installing custom SQL for feedback.EmailTemplate model
(...)
Installing json fixture 'initial_data' from absolute path.
Installed 2 object(s) from 1 fixture(s)
OMERO.web was configured successful. Please start the application.

  • (4.1.0 version only):

    • Settings (optional field can be blank) 

      $ bin/omero web settings
Reconfiguring OMERO.web...
Please enter the domain you want to run OMERO.web on (http://www.domain.com:8000/):http://web.openmicroscopy.org.uk/
Please enter the Email address you want to send from (omero_admin@example.com): web@openmicroscopy.org.uk
Please enter the SMTP server host you want to send from (smtp.example.com): smtp.openmicroscopy.org.uk
Optional: please enter the SMTP server port (default 25): 
Optional: Please enter the SMTP server username: 
Optional: Password: 
Optional: TSL? (yes/no): 
Saving to ~/Desktop/omero/lib/python/omeroweb/custom_settings.py

    • Superuser and Syncdb 

      $ bin/omero web superuser
Please enter Username for OMERO.web administrator: webadmin
Please enter Email address: webadmin@openmicroscopy.org.uk
Please enter password for OMERO.web administrator: 
Please re-enter password for OMERO.web administrator: 
Saving to ~/Desktop/omero/lib/python/omeroweb/initial_data.json

$ bin/omero web syncdb
Database synchronization... 
(...)
Creating table feedback_emailtemplate
Creating table webadmin_gateway
(...)
Installing json fixture 'initial_data' from absolute path.
Installed 7 object(s) from 1 fixture(s)
OMERO.web was prepared. Please start the application.

  • OMERO.web is configured to be started on lightweight development Web server with a commands:

    Start up OMERO.web manually: 

    $ cd ~/Desktop/omero/
$ bin/omero admin ice
Ice 3.3.0  Copyright 2003-2008 ZeroC, Inc.
>>> server enable Web
>>> server start Web
>>> exit

    Shut down OMERO.web manually: 

    $ cd ~/Desktop/omero/
$ bin/omero admin ice
Ice 3.3.0  Copyright 2003-2008 ZeroC, Inc.
>>> server disable Web
>>> server stop Web
>>> exit

    Check status of OMERO.web: 

    $ cd ~/Desktop/omero/
$ bin/omero admin ice
Ice 3.3.0  Copyright 2003-2008 ZeroC, Inc.
>>> server state Web
active (pid 18423)
>>> exit

Once you have deployed and started the server you can use your browser to access the OMERO.webadmin administration interface:

  • http://localhost:8000/webadmin

    OMERO.webadmin login

  • Or have it started automatically:

    If you wish to have the server always on, configure the following in ~/Desktop/omero/etc/grid/default.xml: 

    <server-instance template="ShellTemplate" id="Web" act="always"/>

  • If you require to configure the out of the box setup to listen for webadmin and webclient connections on different host configure the following:

    Configure the following in ~/Desktop/omero/etc/grid/templates.xml by adding after --noreload: 

    <server-template id="WebTemplate"> 
  <parameter name="act" default="on-demand"/> 
  <server id="Web" exe="python" activation="${act}" pwd="${OMEROPY_HOME}omeroweb"> 
    <option>manage.py</option> 
    <option>runserver</option> 
    <option>--noreload</option> 
    <option>0.0.0.0:8000</option><!-- your ip & port here -->
    <env>${PYTHONPATH}</env> 
    <adapter name="WebAdapter" register-process="true" endpoints="tcp" server-lifetime="false"/> 
  </server> 
</server-template>

    In your ~/Desktop/omero/lib/python/omero/plugins/ directory configure the following in server.py: 

    django = ["python","manage.py","runserver","0.0.0.0:8000","--noreload"]+list(args)

Enabling Movie creation from OMERO.

OMERO has the facility to create AVI/MPEG Movies from Images which can be called from Insight. The page OmeroMovie gives details on how to enable them.

Post-installation items

Security

It is now recommended that you read the 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've gotten the base server running, you may want to try enabling some of the advanced features such as FS or LDAP. In the 4.1 release, there is also preview functionality which is described on the HcsPreview wiki page.

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 UpgradeCheck page.

Troubleshooting

My OMERO install doesn't work! What do I do now!?! Examine the Troubleshooting page and if all else fails post a message to our ome-users mailing list discussed on the OmeroCommunity page.

OMERO Diagnostics

If you want help with your server installation, please include the output of the diagnostics command: 

    $ cd ~/Desktop/omero/
    $ bin/omero admin diagnostics

    ================================================================================
    OMERO Diagnostics Beta-4.1.0-DEV
    ================================================================================

    Commands:   java -version                  1.5.0     (/usr/bin/java)
    Commands:   python -V                      2.5       (/opt/local/bin/python -- 2 others)
    Commands:   icegridnode --version          3.3       (/opt/Ice-3.3.0/bin/icegridnode)
    Commands:   icegridadmin --version         3.3       (/opt/Ice-3.3.0/bin/icegridadmin)
    Commands:   psql --version                 8.2.13    (/opt/local/lib/postgresql82/bin/psql)

    Server:     icegridnode                    running
    Server:     Blitz-0                        active (pid = 3142, enabled)
    Server:     DropBox                        inactive (disabled)
    Server:     FSServer                       inactive (disabled)
    Server:     Indexer-0                      active (pid = 3072, enabled)
    Server:     OMERO.Glacier2                 active (pid = 3073, enabled)
    Server:     OMERO.IceStorm                 active (pid = 3074, enabled)
    Server:     Processor-0                    active (pid = 3075, enabled)
    Server:     Tables-0                       active (pid = 3076, enabled)
    Server:     TestDropBox                    inactive (enabled)
    Server:     Web                            inactive (enabled)

    Log dir:    ~/Desktop/omero/var/log exists

    Log files:  Blitz-0.log                    1.0 MB        errors=13   warnings=106 
    Log files:  DropBox.log                    7.0 KB        errors=8    warnings=0   
    Log files:  FSServer.log                   2.0 KB        errors=3    warnings=0   
    Log files:  Indexer-0.log                  39.0 MB       errors=1    warnings=10
    Log files:  OMEROweb.log                   0.0 KB        errors=1    warnings=1   
    Log files:  OMEROweb.log.2009-10-19        0.0 KB        errors=2    warnings=2   
    Log files:  Processor-0.log                5.0 KB        errors=0    warnings=8   
    Log files:  Tables-0.log                   5.0 KB        errors=0    warnings=8   
    Log files:  TestDropBox.log                n/a
    Log files:  master.err                     1.0 KB       
    Log files:  master.out                     0.0 KB       
    Log files:  Total size                     40.66 MB
Document Actions