In addition to the general process described in Set up a Development Machine, follow these extra steps when setting up a Mac for LabKey Development:

Software Installation

  • Install the Apple Mac OS X developer tools. This contains a number of important tools you will need.
  • Java for Mac OS X (FAQs for your reference:
  • Open the Java Preferences application in /Applications/Utilities and ensure that Java SE 8 is at the top of the Java Applications list.
  • Setup Environment variables:
    • CATALINA_HOME = <your_tomcat_home>
    • PATH = <labkey-root>/external/ant/bin:<labkey-root>/external/osx/bin:<your-normal-path>
You can do this via traditional unix methods (in ~/.bash_profile) or via the mac's plist environment system.

To add the environment variables using ~/.bash_profile, edit the file and add the lines:

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
export CATALINA_HOME=$HOME/apps/tomcat
export LABKEY_ROOT=$HOME/labkey/trunk
export LABKEY_GWT_USER_OVERRIDE="gwt-user-firefox"
export PATH=$LABKEY_ROOT/external/ant/bin:$LABKEY_ROOT/build/deploy/bin:$PATH

To add the environment variables using the mac plist editor, open the file ~/.MacOSX/environment.plist. This should open in the plist editor (from Apple developer tools).

  • Create the env vars shown above
  • logout and in


Yosemite does not include ant. LabKey includes ant in LabKey/trunk/external/ant.

To use this version of ant, add the following line to your .bash_profile file (located in /Users/<username>):    export PATH=/LabKey/trunk/external/ant/bin:$PATH

(You'll need to restart Terminal for these changes to take effect across all terminal windows).

(Replace '/LabKey/trunk/external/ant/bin' with wherever your ant is located, of course).

Package managers can be used to install other tools such as git, subversion, etc. Homebrew works pretty well for this :

IntelliJ IDEA

The setup for IntelliJ is described in the common documentation, but a few additional troubleshooting notes may be helpful:

Run/Debug LabKey Error:

  • Could not find or load main class org.apache.catalina.startup.Bootstrap
    • You might see this error in the console when attempting to start LabKey server. Update the '-classpath' VM option for your Run/Debug configuration to have Unix (:) path separators, rather than Windows path separators (;).
SVN annotate/history:
  • Problems while loading file history: svn: E175002
    • Notes on upgrading on Yosemite, with Subversion 1.8.13:
      • From terminal, execute these commands:
      • Get Brew, if you don't have it already: $ ruby -e "$(curl -fsSL"
      • Uninstall svn: $ brew uninstall svn
      • Install svn: $ brew install svn
      • Link: $ brew link --overwrite subversion
      • Test the version: $ svn --version (without successful linking, svn won't be recognized as a valid command)
Note: If you get this error during linking:

Linking /usr/local/Cellar/subversion/1.8.13...

Error: Could not symlink include/subversion-1/mod_authz_svn.h

/usr/local/include/subversion-1 is not writable.

Perform these steps:

Take ownership: $ sudo chown -R $USER /usr/local/include

Try Linking again: $ brew link --overwrite subversion

    • Configure IntelliJ to use the installed binary (
      • from Terminal execute : which svn
      • In IntelliJ, go to 'IntelliJ IDEA' menu --> Preferences --> Version Control --> Subversion --> Under "Use command line client:", copy the resultant path from 'which svn' command --> Apply.


To do development or testing using a database that is not supported on the Mac (e.g., SQL Server or Oracle), it is recommended to set up a VirtualBox instance for the target operating system (Windows or Linux). (This is generally preferred for developers over using Parallels, but the installation instructions once you have an OS installed are the same regardless. )
  1. Download and install Virtual Box :
  2. Create a new Virtual Box VM and install the desired OS on it. The easiest way is to download an ISO file for the OS and use it as the installation media for your VM.
  3. Once the ISO file is downloaded start Virtual Box and create a new VM for your target OS (most defaults are acceptable).
  4. Start the new VM for the first time.
  5. When a VM gets started for the first time, another wizard -- the "First Start Wizard" -- will pop up to help you select an installation medium. Since the VM is created empty, it would otherwise behave just like a real computer with no operating system installed: it will do nothing and display an error message that no bootable operating system was found.
  6. Select the ISO file that was previously downloaded, this should result in the installation wizard getting run.
  7. You may also want to install the Guest Additions for the VM so the window can be expanded to a more usable size ( This will also enable you to share files between your Mac and the VM, which can sometimes be helpful.
  8. Once the OS is installed, you can install your target database on it. See below for specifics on SQLServer or Oracle.
  9. To allow for remote access to the database you've installed, you will need to create a hole for the database connections in the firewall. For Windows, follow the instructions in the "TCP Access" section of this TechNet note using the port number appropriate for your database installation.
  10. You also need to configure Virtual Box so that a connection to the database can be made from the instance of LabKey running on your mac. The easiest way to do this is through port forwarding over NAT.
In the Virtual Box Manager, select your Windows VM and edit the settings, in the network tab, select NAT and click on port forwarding.

Create a new record using TCP, and localhost ( Set the host and guest port to be the same as the configuration in your file (typically 1433) Note: To get the IP address of the Guest OS, you can run "ipconfig" in a command window on the Windows VM. You will want the IPv4 address.

SQL Server on VM

Typically SQL Server Express is adequate for development. Follow the instructions here for the installation. Note that you should not need to do the extra steps to get GROUP_CONCAT installed. It will be installed automatically when you start up LabKey server for the first time pointing to your SQL Server database.

SQL Server Browser Setup

During the installation, you will want to set the SQL Server Browser to start automatically. You can do this from within the SQL Server Configuration Manager. Under SQL Server Services, right click on the SQL Server Browser and open the Properties window Go to the Service tab and change the Start Mode to "Automatic."

Remote Access to SQL Server

To allow for remote access to SQL Server, you will need to:

  1. Create a hole for SQL Server in the Windows firewall. Follow the instructions in the "TCP Access" section of this TechNet note.
  2. make some configuration changes to allow remote connections and set up a login for LabKey server to use:
    • Open SQL Server Management Studio (which is not the same as the SQL Server Configuration Manager)
    • Right click on the <Server Name> and choose Properties -->Connections, check "Allow remote connections to this server"
    • From <Server Name> --> Properties, --> Security, set Server Authentication to “SQL Server & Windows Authentication mode”
    • Click OK and Close the Properties window
    • Choose Security --> Logins --> double click on 'sa' --> Status, set Login to Enabled. This is the user that will be used by LabKey server, so set the password and take note of it.
    • From Sql Server Configuration Manager, select SQL Server Network Configuration --> Protocols for MSSQLSERVER.
      • Enable TCP/IP (If not enabled already).
      • Right Click on TCP/IP --> Properties --> IP Addresses tab
      • Make sure ports with IP Addresses of and other other IP Address (thats used in Port Forwarding that you found using ipconfig), are Enabled.
      • Restart your computer.
  1. Restart SQL Server & SQL Server Browser from the Services control panel.

LabKey Properties Files

  1. Edit the config file under /Labkey/server/configs. If you have setup the NAT forwarding mentioned above, then set the databaseDefaultHost to Otherwise, set the databaseDefaultHost to the windows IP (use ipconfig to find out what this is; you want the IPv4 address) (seems like this is necessary; just using the name of the host instead doesn't seem to work). If you have multiple datasources defined in your labkey.xml file, the IP address needs to be used for those data sources as well.
  2. Edit the config file further by updating the jdbcUser and jdbcPassword information. This is where you use the "sa" user and the password you had setup during the SQL Server install.
  3. Pick SQL Server for LabKey (run "ant pick_mssql" - either from the command line or within IntelliJ)
  4. Restart your LabKey server instance.

Oracle on VM

Oracle Express Edition is probably sufficient for development and testing purposes. Follow the instructions in the installation docs on Oracle's site and then refer to the page for using Oracle as an external data source for some LabKey specifics.

Remote Access to Oracle

After the initial installation, Oracle Database XE will be available only from the local server, not remotely. Be sure to follow the steps for making Oracle available to Remote Clients. In particular, you will need to run the following command from within SQL*Plus connected as the system user


SQL Developer (Oracle Client UI).

For troubleshooting and development, you will probably want to install a version of SQL Developer, the Oracle client application. There is a version of the client that works for the Mac, so it is probably easiest to download and install on your Mac. It may also be useful to install a version on the VM. If installing on the VM, Java is required unless you get the version of SQL Developer that also bundles Java.





expand all collapse all