OMERO.server Installation for UNIX Based Platforms

NOTE: If you are upgrading your OMERO.server installation you want to follow instructions on the OmeroUpgrade page.

NOTE: If you are attempting a Microsoft Windows install please see the OmeroInstallWindows page.

Prerequisites

• PostgreSQL 7.4 or higher installed and configured to accept TCP connections (OmeroAndPostgres)

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

  # 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 javc
  /usr/bin/javc
  $ javac -version
  javac 1.6.0
  

NOTE: The installation of these applications is outside the scope of this document

• OMERO.server tar.bz2 available from MilestoneDownloads

Pre-Installation

(This will require a "root" level account for which you know the password)

• Create a non-superuser database user (make sure to note down the name and password):

  # 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 and 8.3.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 data to reside in:

  sudo -u postgres createdb -O <db_username> <db_name>
  
  ex. sudo -u postgres createdb -O omero omero3
  

• 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 (if you get errors here you should read OmeroAndPostgres):

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

• Create a directory for the OmeroBinaryRepository. NOTE: 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:

  sudo mkdir /OMERO
  

NOTE: /OMERO must either be owned by the user starting JBoss or that user must have permission to write to the directory. You can find out your username and ensure the directory has the correct permissions as follows:

$ whoami
callan
$ sudo chown -R callan /OMERO

Installation

• Extract the OMERO tarball and note its location

• Edit the etc/local.properties file in the OMERO distribution based upon your database user and password choices

  ex. ~/Desktop/omero-3.0-Beta1/omero/etc/local.properties
  

  • One property which it is often useful to change is the omero.data.dir value, which points to your OmeroBinaryRepository.

• The example local.properties file included in the OMERO.server distribution:

  #
  # Default OMERO local.properties file for distribution. Please see:
  #
  #  http://trac.openmicroscopy.org.uk/omero/wiki/OmeroInstall
  #  http://trac.openmicroscopy.org.uk/omero/wiki/OmeroAndPostgres
  #
  # ________________________________
  # Chris Allan <callan@blackcat.ca>
  #
  
  # ********
  # ******** USER CONFIGURABLE OPTIONS
  # ********
  
  # OMERO "root" user's default password. Will be used for "setup-db".
  omero.rootpass=omero
  
  # OMERO server's database connection username. This should match up 
  # with whatever you have set the database username.
  hibernate.connection.username=omero
  
  # OMERO server's database connection password. This should match up 
  # with whatever you have set the database password.
  hibernate.connection.password=omero
  
  # OMERO server's database connection URL. This should match up with 
  # "database.host" and "database.name" below.
  hibernate.connection.url=jdbc\:postgresql\://localhost/omero3
  
  # Database server hostname.
  database.host=localhost
  
  # Database instance name.
  database.name=omero3
  
  # OMERO binary repository directory. Defaults to /OMERO. Please see
  # http://trac.openmicroscopy.org.uk/omero/wiki/OmeroBinaryRepository for
  # more information.
  omero.data.dir=/OMERO/
  
  # ********
  # ******** SYSTEM OPTIONS (DO NOT MODIFY UNLESS INSTRUCTED)
  # ********
  
  # JBoss server's hostname. It is unlikely this is something you will
  # need to change.
  server.host=localhost
  
  # JBoss server's port. It is unlikely this is something you will
  # need to change.you will want to change.
  server.port=1099
  
  # OMERO testing framework's default user. Unless you are performing
  # tests as a developer you will not need to change this.
  omero.user=omero
  
  # OMERO testing framework's default password. Unless you are 
  # performing tests as a developer you will not need to change this.
  omero.pass=omero
  
  # OMERO database profile. Do not change this.
  omero.db.profile=psql
  
  # Java compiler options.
  javac.source=1.5
  javac.target=1.5
  javac.debug=on
  javac.debuglevel=lines,vars,source
  
  # ICE compilation options. Do not change.
  no.ice=false
  ice.home=/usr/share/Ice
  
  # PostgreSQL profile setup. Do not change these.
  hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
  hibernate.connection.driver_class=org.postgresql.Driver
  

• Initialize the OMERO database, deploy the OMERO EAR and start OMERO:

  cd ~/Desktop/omero-3.0-Beta2.3/omero 
  export JBOSS_HOME=~/Desktop/omero-3.0-Beta2.3/jboss-4.2.1.GA 
  java omero setup-db deploy
  $JBOSS_HOME/bin/run.sh 
  

(To start OMERO.server in the background: $JBOSS_HOME/bin/run.sh > /dev/null 2>&1)

Administration

Once you have deployed and started the server you can use your browser to access the OMERO WebAdmin administration interface (included with the bundled JBoss server) at:

• http://localhost:8080/WebAdmin/

Assuming you're using the default local.properties file (also annotated above), the default username is root and the default password is omero:

Reconfiguration

If at any time you change the vales of of the property files contained under etc you will need to update the EAR file and redeploy, for example:

export JBOSS_HOME=~/Desktop/omero-3.0-Beta2.3/jboss-4.2.1.GA
java omero deploy

Update Notification

As of milestone:3.0-Beta2.3, 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.

Security

It is now recommended that you read the OmeroSecurity 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.

/OMERO is not where I want my binary repository to be!

You can change the location of your OMERO.server binary repository by following the instructions on the OmeroBinaryRepository page.

Troubleshooting

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

---

See also: MilestoneDownloads, OmeroInstallWindows, OmeroBinaryRepository, OmeroCommunity, OmeroSecurity, OmeroLdap, OmeroAndPostgres, OmeroTroubleshooting, OmeroUpgrade, UpgradeCheck