This page provides an example of how to perform a complete installation of LabKey's Flow Cytometry Server v8.1 on Mac OSX.

Items installed via these instructions:

  • Sun Java
  • Xcode
  • Apache Tomcat
  • Postgres
  • LabKey Server
Items not installed via these instructions: Characteristics of the target server for the LabKey Server install:
  • Mac OSX 10.5.3 (Leopard)
Note:
  • These instructions assume that you will run the LabKey Flow Cytometry server as a user named "labkey".
  • All downloaded files will be placed in a sub-directory of my home directory /Users/bconn/Download

Install Sun Java

The Sun Java JDK is installed by default on Mac OSX 10.5.x.

Note: <YourServerName> represents the name of the server where you plan to install LabKey Server

<YourServerName>:~ bconn$ java -version
java version "1.5.0_13"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-b05-237)
Java HotSpot(TM) Client VM (build 1.5.0_13-119, mixed mode, sharing)

Install XCode

XCode is the MacOSX development tools. It is a free download from Apple. This is required to compile Postgres and provides you with other development and open source tools.

Install Apache

We will be

  • Using Tomcat v5.5.26
  • Installing Tomcat in the directory /usr/local/apache-tomcat-5.5.26
  • Tomcat will be configured to use port 8080 (see the Configure the Tomcat Default Port section on Configure the LabKey Web Application to change the Default Port )
  • Tomcat will not be configured to use SSL (see the Configure LabKey Server to Run Under SSL (Optional, Recommended) section on Configure the LabKey Web Application to configure your server to use SSL )

Download and unpack Tomcat v5.5.26

<YourServerName>:~ bconn$ cd ~/Download
<YourServerName>:Download bconn$ curl
http://apache.oc1.mirrors.redwire.net/tomcat/tomcat-5/v5.5.26/bin/apache-tomcat-5.5.26.tar.gz -o
apache-tomcat-5.5.26.tar.gz
<YourServerName>:Download bconn$ sudo -s
bash3.2# cd /usr/local
bash3.2# tar xzf ~/Download/apache-tomcat-5.5.26.tar.gz
bash3.2# cd apache-tomcat-5.5.26/
bash3.2# ls
bin common conf LICENSE logs NOTICE RELEASE-NOTES RUNNING.txt server shared temp webapps work

Create the labkey user

  • This user will be the user that runs the tomcat server.
  • This user will have the following properties
    • UID=900
    • GID=900
    • Home Directory= /Users/labkey
    • Password: No password has been set. This means that you will not be able to login as the user labkey. If you want to run as the user labkey you will need to run sudo su - labkey from the command line.
First create the labkey group and create the home directory
bash-3.2# dseditgroup -u USERNAME -P PASSWORD -o create -n . -r "labkey" -i 900 labkey
bash-3.2# mkdir /Users/labkey

Create the labkey user

bash-3.2# dscl . -create /Users/labkey
bash-3.2# dscl . -create /Users/labkey UserShell /bin/bash
bash-3.2# dscl . -create /Users/labkey RealName "LabKey User"
bash-3.2# dscl . -create /Users/labkey UniqueID 900
bash-3.2# dscl . -create /Users/labkey PrimaryGroupID 900
bash-3.2# dscl . -create /Users/labkey NFSHomeDirectory /Users/labkey

Now lets view the user setup

bash-3.2# dscl . -read /Users/labkey
AppleMetaNodeLocation: /Local/Default
GeneratedUID: A695AE43-9F54-4F76-BCE0-A90E239A9A58
NFSHomeDirectory: /Users/labkey
PrimaryGroupID: 900
RealName:
LabKey User
RecordName: labkey
RecordType: dsRecTypeStandard:Users
UniqueID: 900
UserShell: /bin/bash

Set up the users .bash_profile file

bash-3.2# vi ~labkey/.bash_profile
Add the following to the file
#Created to be used for starting up the LabKey Server
JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
CATALINA_HOME=/usr/local/apache-tomcat-5.5.26
CATALINA_OPTS=-Djava.awt.headless=true
export CATALINA_OPTS
export JAVA_HOME
export CATALINA_HOME
# Append Path
PATH=$PATH:/usr/local/pgsql/bin:/usr/local/bin:/usr/local/labkey/bin


bash-3.2# chown -R labkey.labkey /Users/labkey

Lets set the proper permissions on the Tomcat directories

bash-3.2# chown -R labkey.labkey /usr/local/apache-tomcat-5.5.26

Configure the Tomcat server

Enable Access Logging on the server(This allows you to see which URLs are accessed):

bash-3.2# vi /usr/local/apache-tomcat-5.5.26/conf/server.xml

Change:

<!--
<Valve className="org.apache.catalina.valves.FastCommonAccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="common" resolveHosts="false"/>
-->
To:
<Valve className="org.apache.catalina.valves.FastCommonAccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="combined" resolveHosts="false"/>

Create "init" script that will be used to start and stop the tomcat server

Here we use the JSVC tool to create an init script. The JSVC is an Apache project and is shipped with the Tomcat distribution. There are many ways you can create an init script, but for this example, this is the tool we used.

Build JSVC Daemon

Note: You need to build this package. In order to do so, you will need GCC, Autoconf. These are installed with with the XCode package Note2: In addition, you need to make sure the JAVA_HOME environment variable is set for the user building this software

bash-3.2# cd /usr/local/
bash-3.2# tar xzf /usr/local/apache-tomcat-5.5.26/bin/jsvc.tar.gz

Before we get started, we need to modify two files in the distribution to have them compile properly on Leopard

bash-3.2# export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
bash-3.2# cd /usr/local/jsvc-src/
bash-3.2# vi native/jsvc.h
Change:
/* Definitions for booleans */
typedef enum {
false,
true
} bool;
To:
#include <stdbool.h>

bash-3.2# vi support/apsupport.m4
Change:
CFLAGS="$CFLAGS -DOS_DARWIN -DDSO_DYLD"
To:
CFLAGS="$CFLAGS -DOS_DARWIN -DDSO_DLFCN"

Now we can perform the build

bash-3.2# sh support/buildconf.sh
bash-3.2# sh ./configure
...
bash-3.2# make
...

You will see some warning messages produced, but it will be successful compile and the JSVC daemon will created at /usr/local/jsvc-src/jsvc

Install JSVC Daemon

bash-3.2# mkdir /usr/local/jsvc
bash-3.2# cp /usr/local/jsvc-src/jsvc /usr/local/jsvc

Configure the server to Start Tomcat using the JSVC daemon at boot-time

On Mac OSX this is a little more complicated to setup than on other unix platforms. There are 2 steps to this process
  1. Create "start-up" script
  2. Create plist file (file that launchd reads to start the Tomcat process )
Create the start-up script

bash-3.2# vi /usr/local/jsvc/Tomcat5.sh 
#!/bin/sh
##############################################################################
#
# Copyright 2004 The Apache Software Foundation.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
##############################################################################
#
# Small shell script to show how to start/stop Tomcat using jsvc
# If you want to have Tomcat running on port 80 please modify the server.xml
# file:
#
# <!-- Define a non-SSL HTTP/1.1 Connector on port 80 -->
# <Connector className="org.apache.catalina.connector.http.HttpConnector"
# port="80" minProcessors="5" maxProcessors="75"
# enableLookups="true" redirectPort="8443"
# acceptCount="10" debug="0" connectionTimeout="60000"/>
#
# That is for Tomcat-5.0.x (Apache Tomcat/5.0)
#
# chkconfig: 3 98 90
# description: Start and Stop the Tomcat Server
#
#Added to support labkey
PATH=$PATH:/usr/local/labkey/bin
export PATH
#
# Adapt the following lines to your configuration
JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
CATALINA_HOME=/usr/local/apache-tomcat-5.5.26
DAEMON_HOME=/usr/local/jsvc
TOMCAT_USER=labkey

# for multi instances adapt those lines.
TMP_DIR=/var/tmp
PID_FILE=/var/run/jsvc.pid
CATALINA_BASE=/usr/local/apache-tomcat-5.5.26

CATALINA_OPTS=""
CLASSPATH= $JAVA_HOME/lib/tools.jar: $CATALINA_HOME/bin/commons-daemon.jar: $CATALINA_HOME/bin/bootstrap.jar

case "$1" in
start)
#
# Start Tomcat
#
$DAEMON_HOME/jsvc -user $TOMCAT_USER -home $JAVA_HOME -Dcatalina.home=$CATALINA_HOME -Dcatalina.base=$CATALINA_BASE -Djava.io.tmpdir=$TMP_DIR -wait 10 -pidfile $PID_FILE -outfile $CATALINA_HOME/logs/catalina.out -errfile '&1' $CATALINA_OPTS -cp $CLASSPATH org.apache.catalina.startup.Bootstrap
#
# To get a verbose JVM
#-verbose # To get a debug of jsvc.
#-debug exit $?
;;

stop)
#
# Stop Tomcat
#
$DAEMON_HOME/jsvc -stop -pidfile $PID_FILE org.apache.catalina.startup.Bootstrap
exit $?
;;

*)
echo "Usage Tomcat5.sh start/stop"
exit 1;;
esac

_Create the plist file_

bash-3.2$ vi /Library/LaunchDaemons/org.apache.commons.jsvc.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Disabled</key>
<false/>
<key>Label</key>
<string>org.apache.commons.jsvc</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/jsvc/Tomcat5.sh</string>
<string>start</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>WorkingDirectory</key>
<string>/usr/local/apache-tomcat-5.5.26</string>
</dict>
</plist>

Test Tomcat Installation

First, lets test if Apache is installed properly.

bash-3.2# export JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
bash-3.2# export CATALINA_HOME=/usr/local/apache-tomcat-5.5.26
bash-3.2# export CATALINA_OPTS=-Djava.awt.headless=true
bash-3.2# /usr/local/apache-tomcat-5.5.26/bin/startup.sh
Goto http://localhost:8080/ and test to see if the Tomcat startup page is returned.

Second, lets test the "start-up" script that uses JSVC

bash-3.2# /usr/local/apache-tomcat-5.5.26/bin/shutdown.sh
bash-3.2# /usr/local/jsvc/Tomcat5.sh start
Goto http://localhost:8080/ and test to see if the Tomcat startup page is returned.

Lastly, lets test to see if the LauncherDaemon is configured properly

bash-3.2# /usr/local/jsvc/Tomcat5.sh stop
bash-3.2# launchctl load /Library/LaunchDaemons/org.apache.commons.jsvc.plist
Goto http://localhost:8080/ and test to see if the Tomcat startup page is returned.

If all the tests have passed, then the Tomcat installation was a success. Shutdown the Tomcat server at this time

bash-3.2# /usr/local/jsvc/Tomcat5.sh stop
bash-3.2# exit

Postgres Installation and Configuration

We will download and build Postgres from source. There are some binary versions of Postgres for Mac, but the official documentation recommends building from source.

We will be

  • Using Postgresql v8.2.6
  • Installing Postgresql in the directory /usr/local/pgsql
  • The postgres server will be run as the user postgres which will be created.
  • New super-user role named labkey will be created and used by the Tomcat server to talk to postgres

Download and expand the source

<YourServerName>:Download bconn$ curl 
http://ftp7.us.postgresql.org/pub/postgresql//source/v8.2.9/postgresql-8.2.9.tar.gz
-o postgresql-8.2.9.tar.gz
<YourServerName>:Download bconn$ sudo su -
bash-3.2# cd /usr/local
bash-3.2#tar -xzf ~bconn/Download/postgresql-8.2.9.tar.gz

Build Postgres

bash-3.2# ./configure
bash-3.2# make
...
bash-3.2# make check
...
bash-3.2# make install
...

Create the labkey user

  • This user will be the user that runs the postgres server.
  • This will create a user named postgres
  • This user will have the following properties
    • UID=901
    • GID=901
    • Home Directory=/usr/local/pgsql
    • Password: No password has been set. This means that you will not be able to login as the user postgres. If you want to run as the user postgres you will need to run sudo su - postgres from the command line.
First create the postgres group
dseditgroup -o create -n . -r "postgres" -i 901 postgres

Create the postgres user

bash-3.2# dscl . -create /Users/postgres
bash-3.2# dscl . -create /Users/postgres UserShell /bin/bash
bash-3.2# dscl . -create /Users/postgres RealName "Postgres User"
bash-3.2# dscl . -create /Users/postgres UniqueID 901
bash-3.2# dscl . -create /Users/postgres PrimaryGroupID 901
bash-3.2# dscl . -create /Users/postgres NFSHomeDirectory /usr/local/pgsql

Now lets view the user setup

bash-3.2# dscl . -read /Users/postgres
AppleMetaNodeLocation: /Local/Default
GeneratedUID: A695AE43-9F54-4F76-BCE0-A90E239A9A58
NFSHomeDirectory: /usr/local/pgsql
PrimaryGroupID: 901
RealName:
Postgres User
RecordName: postgres
RecordType: dsRecTypeStandard:Users
UniqueID: 901
UserShell: /bin/bash

Initialize the Postgres database

Create the directory which will hold the databases
bash-3.2# mkdir /usr/local/pgsql/data
bash-3.2# mkdir /usr/local/pgsql/data/logs
The postgres user will need to own the directory
bash-3.2# chown -R postgres.postgres /usr/local/pgsql/data
Initialize the Postgres server
bash-3.2# su - postgres
<YourServerName>:pgsql postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
Start the Postgres server
<YourServerName>:pgsql postgres$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l 
/usr/local/pgsql/data/postgres.log start

Create a new database super-user role named "labkey":

<YourServerName>:pgsql postgres$ /usr/local/pgsql/bin/createuser -P -s -e labkey
Enter password for new role:
Enter it again:
CREATE ROLE "labkey" PASSWORD 'LabKey678' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;
CREATE ROLE

Add the PL/pgsql language support to the postgres configuration

<YourServerName>:pgsql postgres$ createlang -d template1 PLpgsql

Change authorization so that the labkey user can login.

By default, postgres uses the ident method to authenticate users. However, the ident daemon is not available on many servers. Thus we have decided to use the "password" authentication method for all local connections. See http://www.postgresql.org/docs/8.2/static/auth-methods.html for more information on authentication methods.

Stop the server

<YourServerName>:pgsql postgres$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l 
/usr/local/pgsql/logs/logfile stop
<YourServerName>:pgsql postgres$ exit

Edit the pg_hba.cfg file

bash-3.2# vi /usr/local/pgsql/data/pg_hba.cfg
Change:
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

# "local" is for Unix domain socket connections only
local all all ident sameuser
# IPv4 local connections:
host all all 127.0.0.1/32 ident sameuser
# IPv6 local connections:
host all all ::1/128 ident sameuser
To:
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

# "local" is for Unix domain socket connections only
local all all ident sameuser
# IPv4 local connections:
host all all 127.0.0.1/32 password
# IPv6 local connections:
host all all ::1/128 ident sameuser

Increase the join collapse limit.

This allows the LabKey server to perform complex queries against the database.

bash-3.2# vi /var/lib/pgsql/data/postgresql.conf Change:

# join_collapse_limit = 8
To:
join_collapse_limit = 10

If you do not do this step, you may see the following error when running complex queries: org.postgresql.util.PSQLException: ERROR: failed to build any 8-way joins

Start the postgres database

<YourServerName>:pgsql postgres$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l 
/usr/local/pgsql/data/logs/logfile start

Create the "init" script that will start Postgres at boot-time

Luckily, with Postgres, there are scripts that ship with the source that can be used to start the Postgres server at boot-time. Postgres will use a different mechanism for getting started than Tomcat.

Create the required directories and copy of the Startup files from the source directory

bash-3.2# mkdir /Library/StartupItems/PostgreSQL/
bash-3.2# cp /usr/local/postgresql-8.2.9/contrib/start-scripts/PostgreSQL.darwin
/Library/StartupItems/PostgreSQL/PostgreSQL
bash-3.2# cp /usr/local/postgresql-8.2.9/contrib/start-scripts/StartupParameters.plist.darwin
/Library/StartupItems/PostgreSQL/StartupParameters.plist

Change the configuration of the start-up script to disable log rotation

bash-3.2# vi /Library/StartupItems/PostgreSQL/PostgreSQL
Change:
# do you want to rotate the log files, 1=true 0=false
ROTATELOGS=1
To:
# do you want to rotate the log files, 1=true 0=false
ROTATELOGS=0

Install Graphviz

Download and expand Graphviz

<YourServerName>:Download bconn$ curl 
http://www.graphviz.org/pub/graphviz/ARCHIVE/graphviz-2.16.1.tar.gz
-o graphviz-2.16.1.tar.gz
<YourServerName>:Download bconn$ sudo su -
bash-3.2# cd /usr/local
bash-3.2#tar -xzf ~bconn/Download/graphviz-2.16.1.tar.gz

Build and install Graphviz binaries into /usr/local/bin

bash-3.2# tar xzf ~/Downloads/graphviz-2.16.1.tar.gz 
bash-3.2# /usr/local/graphviz-2.16.1
bash-3.2# ./configure
...
bash-3.2# make
...
bash-3.2# make install
...

Install LabKey Server

Note: Starting in LabKey Server version 13.3, the JAR distribution directories /common-lib and /server-lib were consolidated to a single directory /tomcat-lib. The destination for these JARs was changed to TOMCAT_HOME/lib. If you are installing 13.3 or later, modify the commands below accordingly.

Download and expand LabKey server

Download LabKey Server from http://www.labkey.com and place the tar.gz file into your Download directory
bash-3.2# cd /usr/local
bash-3.2# tar xzf ~bconn/Download/LabKey8.2-XXXX-bin.tar.gz
bash-3.2# cd LabKey8.2-XXXX-bin
bash-3.2# ls
common-lib labkeywebapp labkey.xml modules README.txt server-lib manual-upgrade.sh

Copy the jars in the common-lib directory the <CATALINA_HOME>/common/lib:

bash-3.2# cd common-lib/
bash-3.2# ls
activation.jar jtds.jar mail.jar postgresql.jar
bash-3.2# cp *.jar /usr/local/apache-tomcat-5.5.26/common/lib/

Copy the jars in the server-lib directory the <TOMCAT_HOME>/server/lib

bash-3.2# cd ../server-lib/
bash-3.2# ls
labkeyBootstrap.jar
bash-3.2# cp *.jar /usr/local/apache-tomcat-5.5.26/server/lib/

Create the <LABKEY_HOME> directory:

bash-3.2# mkdir /usr/local/labkey

Copy the labkeywebapp and the modules directory to the <LABKEY_HOME> directory:

bash-3.2# cd ..
bash-3.2# ls
common-lib labkeywebapp labkey.xml modules README.txt server-lib manual-upgrade.sh
bash-3.2# mkdir /usr/local/labkey/labkeywebapp
bash-3.2# mkdir /usr/local/labkey/modules
bash-3.2# cp -R labkeywebapp/* /usr/local/labkey/labkeywebapp/
bash-3.2# cp -R modules/* /usr/local/labkey/modules/

Copy the labkey.xml file to the <CATALINA_HOME> directory and make the necessary changes to the file:

bash-3.2# cp labkey.xml /usr/local/apache-tomcat-5.5.26/conf/Catalina/localhost/
bash-3.2# vi /usr/local/apache-tomcat-5.5.26/conf/Catalina/localhost/labkey.xml

The file was changed to look like this:

<Context path="/labkey" docBase="/usr/local/labkey/labkeywebapp" debug="0" 
reloadable="true" crossContext="true">

<Environment name="dbschema/--default--" value="jdbc/labkeyDataSource"
type="java.lang.String"/>

<Resource name="jdbc/labkeyDataSource" auth="Container"
type="javax.sql.DataSource"
username="labkey"
password="LabKey678"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost/labkey"
maxActive="20"
maxIdle="10" accessToUnderlyingConnectionAllowed="true"/>

<Resource name="jms/ConnectionFactory" auth="Container"
type="org.apache.activemq.ActiveMQConnectionFactory"
factory="org.apache.activemq.jndi.JNDIReferenceFactory"
description="JMS Connection Factory"
brokerURL="vm://localhost?broker.persistent=false&amp;broker.useJmx=false"
brokerName="LocalActiveMQBroker"/>

<Resource name="mail/Session" auth="Container"
type="javax.mail.Session"
mail.smtp.host="localhost"
mail.smtp.user="labkey"
mail.smtp.port="25"/>

<Loader loaderClass="org.labkey.bootstrap.LabkeyServerBootstrapClassLoader"
useSystemClassLoaderAsParent="false" />

<!-- <Parameter name="org.mule.webapp.classpath" value="C:mule-config"/> -->

</Context>

The final step is to make the labkey user the owner of all files in <CATALINA_HOME> and <LABKEY_HOME>:

["error">root@<YourServerName> LabKey2.3-7771-bin?]# chown -R labkey.labkey /usr/local/labkey
["error">root@<YourServerName> LabKey2.3-7771-bin?]# chown -R labkey.labkey /usr/local/apache-tomcat-5.5.26

Now start LabKey Server to test it:

bash-3.2# /usr/local/jsvc/Tomcat5.sh start

You can access LabKey Server at

http://<YourServerName>:8080/labkey
If you are experiencing any problem, the log files are located at /usr/local/apache-tomcat-5.5.26/logs.


previousnext
 
expand allcollapse all