LabKey Server's functionality is packaged inside of modules. For example, the query module handles the communication with the databases, the wiki module renders Wiki/HTML pages in the browser, the assay module captures and manages assay data, etc.

You can extend the functionality of the server by adding your own module. Here is a partial list of things you can do with a module:

  • Create a new assay type to capture data from a new instrument.
  • Add a new set of tables and relationships (= a schema) to the database by running a SQL script.
  • Develop file-based SQL queries, R reports, and HTML views.
  • Build a sequence of scripts that process data and finally insert it into the database.
  • Define novel folder types and web part layouts.
  • Set up Extract-Transform-Load (ETL) processes to move data between databases.
Modules provide an easy way to distribute and deploy code to other servers, because they are packaged as single .module files, really just a renamed .zip file. When the server detects a new .module file, it automatically unzips it, and deploys the module resources to the server. In many cases, no server restart is required. Also, no compilation is necessary, assuming the module does not contain Java code or JSP pages.

The following tutorial shows you how to create your own "Hello World" module and deploy it to a local testing/development server.

Set Up a Development Machine

In this step you will set up a test/development machine, which compiles LabKey Server from its source code.

If you already have a working build of the server, you can skip this step.

  • Download the server source code and complete an initial build of the server by completing the steps in the following topic: Set Up a Development Machine
  • Before you proceed, build and deploy the server. Confirm that the server is running by visiting the URL http://localhost:8080/labkey/project/home/begin.view?
  • For the purposes of this tutorial, we will call the location where you have synced the server source code <LABKEY_HOME>. On Windows, a typical location for <LABKEY_HOME> would be C:/dev/labkey/trunk

Module Properties

In this step you create the main directory for your module and set basic module properties.

  • Go to <LABKEY_HOME>, the directory where you synced to the server source code.
  • Inside <LABKEY_HOME>/server/modules, create a directory named "helloworld".
  • Inside the helloworld directory, create a file named "", resulting in the following:
  • Add the following property/value pairs to This is a minimal list of properties needed for deployment and testing. You can add a more complete list of properties later on, including your name, links to documentation, required server and database versions, etc. For a complete list of available properties see Reference.
Name: HelloWorld
ModuleClass: org.labkey.api.module.SimpleModule
Version: 1.0

Build and Deploy the Module

  • Add a file named "build.gradle" to the root directory of your module, resulting in: <LABKEY_HOME>/server/modules/helloworld/build.gradle
  • Add these lines to the file build.gradle:
apply plugin: 'java'
apply plugin: 'org.labkey.fileModule'
  • Open the file settings.gradle (at <LABKEY_HOME>/settings.gradle) and add the following line to the bottom of the file:
include ":modules:helloworld"
  • Confirm that your module will be included in the build:
    • Open a command window.
    • Go to the directory <LABKEY_HOME>
    • Call the Gradle task:
gradlew projects

In the list of projects, you should see the following:

Root project


+--- Project ':modules'
| --- Project ':modules:helloworld'

  • Build and deploy the server by calling the Gradle task:
gradlew deployApp

OR, for a more targeted build, you can call the gradle task:

gradlew :server:modules:helloworld:deployModule

Confirm the Module Has Been Deployed

  • Start the server:
gradlew startTomcat
  • In a browser go to: http://localhost:8080/labkey/project/home/begin.view?
  • Sign in.
  • Confirm that HelloWorld has been deployed to the server by going to (Admin) > Site > Admin Console. Click the Module Information tab. Open the node HelloWorld. Notice the module properties you specified are displayed here: Name: HelloWorld, Version: 1.0, etc.

Add a Default Page

Each module has a default home page called "begin.view". In this step we will add this page to our module. The server interprets your module resources based on a fixed directory structure. By reading the directory structure and the files inside, the server knows their intended functionality. For example, if the module contains a directory named "assays", this tells the server to look for XML files that define a new assay type. Below, we will create a "views" directory, telling the server to look for HTML and XML files that define new pages and web parts.

  • Inside helloworld, create a directory named "resources".
  • Inside resources, create a directory named "views".
  • Inside views, create a file named "begin.html". (This is the default page for any module.)
│ build.gradle
  • Open begin.html in a text editor, and add the following HTML code:
<p>Hello, World!</p>

Test the Module

  • Start and stop the tomcat server using 'gradlew stopTomcat' and then 'gradlew startTomcat'.
  • Build the server using 'gradlew deployApp', or in the module directory, use 'gradlew deployModule'.
  • Wait for the server to redeploy.
  • Navigate to some test folder on your server.
  • Confirm that the view has been deployed to the server by going to (Admin) > Go to Module > HelloWorld.
  • The begin.html file you created is displayed as a webpart like this. Notice the URL ends with "HelloWorld-begin.view?":

Note: If you do not see this view, try enabling the module in your folder as follows:
  • Go to (Admin) > Folder > Management and click the Folder Type tab.
  • In the list of modules on the right, place a checkmark next to HelloWorld.
  • Click Update Folder.

Modify the View with Metadata

You can control how a view is displayed by using a metadata file. For example, you can define the title, framing, and required permissions.

  • Add a file to the views directory named "begin.view.xml". Note that this file has the same name (minus the file extension) as begin.html: this tells the server to apply the metadata in begin.view.xml to being.html.
│ build.gradle
  • Add the following XML to begin.view.xml. This tells the server to: display the title 'Begin View', display the HTML without any framing, and that Reader permission is required to view it.
<view xmlns="" 
title="Begin View"
<permission name="read"/>
  • Save the file.
  • Refresh your browser to see the result. (You do not need to rebuild or restart the server.)
  • The begin view now looks like the following:
  • Experiment with other possible values for the 'frame' attribute:
    • portal (If no value is provided, the default is 'portal'.)
    • title
    • dialog
    • div
    • left_navigation
    • none
  • When you are ready to move to the next step, set the 'frame' attribute to 'portal'.

Hello World Web Part

You can also package the view as a web part using another metadata file.

  • In the helloworld/resources/views directory add a file named "begin.webpart.xml". This tells the server to surface the view inside a webpart. Your module now has the following structure:
│ build.gradle
  • Paste the following XML into begin.webpart.xml:
<webpart xmlns="" 
title="Hello World Web Part">
<view name="begin"/>
  • Save the file.
  • Return to your test folder using the project menu in the upper left.
  • Enable the Hello World module in your folder, if you did not do so earlier:
    • Go to (Admin) > Folder > Management and click the Folder Type tab.
    • In the list of modules on the right, place a checkmark next to HelloWorld.
    • Click Update Folder.
  • In your test folder, enter > Page Admin Mode, then click the pulldown menu that will appear: <Select Web Part>.
  • Select the web part Hello World Web Part and click Add.
  • The following web part will be added to the page:
  • Click Exit Admin Mode.

Hello World User View

The final step provides a more interesting view that uses the JavaScript API to retrieve information about the current user.

  • Open begin.html and replace the HTML with the content below.
  • Refresh the browser to see the changes. (You can directly edit the file begin.html in the module -- the server will pick up the changes without needing to rebuild or restart.)
<p>Hello, <script>

<p>Your account info: </p>
<tr><td>id</td><td><script>document.write(; </script><td></tr>
<tr><td>displayName</td><td><script>document.write(LABKEY.Security.currentUser.displayName); </script><td></tr>
<tr><td>email</td><td><script>document.write(; </script><td></tr>
<tr><td>canInsert</td><td><script>document.write(LABKEY.Security.currentUser.canInsert); </script><td></tr>
<tr><td>canUpdate</td><td><script>document.write(LABKEY.Security.currentUser.canUpdate); </script><td></tr>
<tr><td>canUpdateOwn</td><td><script>document.write(LABKEY.Security.currentUser.canUpdateOwn); </script><td></tr>
<tr><td>canDelete</td><td><script>document.write(LABKEY.Security.currentUser.canDelete); </script><td></tr>
<tr><td>isAdmin</td><td><script>document.write(LABKEY.Security.currentUser.isAdmin); </script><td></tr>
<tr><td>isGuest</td><td><script>document.write(LABKEY.Security.currentUser.isGuest); </script><td></tr>
<tr><td>isSystemAdmin</td><td><script>document.write(LABKEY.Security.currentUser.isSystemAdmin); </script><td></tr>
  • Save the file.
  • Once you've refreshed the browser, the web part will display the following.
  • Also, try out rendering a query in your view. The following renders the table core.Modules, a list of all of the modules available on the server.
<div id='queryDiv'/>
<script type="text/javascript">
var qwp1 = new LABKEY.QueryWebPart({
renderTo: 'queryDiv',
title: 'LabKey Modules',
schemaName: 'core',
queryName: 'Modules',
filters: [
LABKEY.Filter.create('Organization', 'LabKey')

Make a .module File

You can distribute and deploy a module to a production server by making a helloworld.module file (a renamed .zip file).

  • In anticipation of deploying the module on a production server, add the property 'BuildType: Production' to the file:
Name: HelloWorld
ModuleClass: org.labkey.api.module.SimpleModule
Version: 1.0
BuildType: Production
  • Rebuild the module by going to the module directory and calling:
gradlew deployModule
  • The build process creates a helloworld.module file at:

This file can be deployed by copying it to a production server's externalModules directory, or by deploying it through the server UI. When the server detects changes in this directory, it will automatically unzip the .module file and deploy it. You may need to restart the server to fully deploy the module.

Here is a completed helloworld module: helloworld.module

Related Topics

These topics show more functionality that you can package as a module:

These topics describe the build process generally:


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all