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:
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 DaemonNote: 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:
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 Daemonbash-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
- Create "start-up" script
- Create plist file (file that launchd reads to start the Tomcat process )
Create the start-up scriptbash-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:
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&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.