For users interested in using Docker with LabKey Server, we offer an installer that utilizes Spring Boot's "Embedded Tomcat." This installer is offered as a Beta and is meant for use with our Dockerfile repo.

You'll find more guidance here:

Background: In an effort to mitigate the challenges of managing the underlying dependencies and to minimize the complexity of configuring new LabKey installations, LabKey has begun the process of migrating to embedded Tomcat. Switching to an embedded Tomcat distribution method allows us to centralize many configuration parameters into an file, define recommended defaults, and to package and ship Tomcat with the application.



  • Docker: v20.10.9 (or greater) recommended
  • docker-compose: v1.29.2 (or greater) recommended
  • GNU Make
  • GNU Awk
Optional, but not required:
  • AWS CLI - used to publish containers to AWS ECR service.

Obtain the Embedded Tomcat Jar File

Clone the DockerFile repository to a local directory on your docker equipped machine:

git clone

Register to download the distribution here:

Build the LabKey Embedded Docker Container

Once you have the .jar file in your local Dockerfile repo, follow these steps: 1. Export the minimal required environment variables or edit and source the

cd ./Dockerfile/
export LABKEY_VERSION="21.9.0"
source ./

2. Run the Make Build command to create the container

make build

Since the make file supports other features such as publishing to AWS Elastic Container Registry, you may see some warning messages in the Docker build log regarding this if you do not have AWS credentials. These warning messages may be ignored.

Start the LabKey Embedded Docker Container

Once the container has been built, follow these steps to start it:

1. Run the Make Up command to start the container using the makefile docker-compose settings

cd ./Dockerfile/
make up

2. After a few minutes LabKey should be available by opening a browser window and connecting to:

Known Limitations and Considerations

  • LabKey with Embedded Tomcat is currently experimental. Several features of LabKey Server will not work and need to be implemented via other Docker containers. For example: "R" and Python scripting engines.
  • Other known limitations include: Full Text Search and connections to external databases will not work as on a traditional distribution.
  • LabKey Application logs in the example container are redirected to the Docker Host console. This is accomplished via the example log4j2.xml configuration file. This allows consolidation of the logs to be consumed by an external service such as AWS Cloudwatch. In this configuration, the LabKey application and error logs are not viewable in the LabKey Admin Console.

Application Properties File

Configuring LabKey with Embedded Tomcat makes use of application properties. Both Spring Boot's default properties and LabKey specific ones are used. An example file is available here:

The Spring Boot properties are documented here: LabKey-specific properties are documented here: An example file which contains some values referenced in is available here:


Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all