Skip to content

Running LabOne in a Docker container

Docker is a popular and convenient way to distribute and manage applications.

With Docker, applications are packaged into containers, standalone units that bundle an application and all its dependencies. Using containers allows to run multiple applications on the same machine, with a high degree of separation between them but more efficiently than using virtual machines.

Important

Docker runs natively only on Linux. While it's possible to use it on MacOS or Windows (using WSL, the Windows subsystem for Linux), it requires advanced networking configurations. Zurich Instruments officially supports only Docker on Linux.

How to run LabOne with Docker

First install Docker following the official instructions.

To start LabOne, run: 

$ docker run -d --rm --name labone-full --network=host zhinst/labone:25.1-full
This will automatically download the LabOne image from Docker Hub and start it.

You can check that LabOne is running using docker ps: 

$ docker ps
CONTAINER ID   IMAGE                      COMMAND       CREATED         STATUS         PORTS     NAMES
023f21ef2738   zhinst/labone:25.1-full   "/start.sh"   5 minutes ago   Up 5 minutes             labone-full
To stop the container, use docker stop: 
$ docker stop labone-full

When should I use the LabOne Docker image?

Using the Docker version of LabOne can be a good option in the following cases:

  • You already use Docker to deploy other applications and would like to manage LabOne in the same way.
  • You have a single server shared by multiple users, running different applications. Using containers can be more convenient than installing software on the machine directly.
  • You want to switch quickly between different versions of LabOne. With Docker, you don't need to install/uninstall LabOne to switch version, but can switch between running different Docker containers.

Important

Using Docker does not allow to run multiple instances of LabOne on the same machine.

When should I not use Docker?

Properly configuring Docker can be challenging. This is why we don't recommend using it unless you are already familiar with it. Instead of using the Docker images, you can install LabOne directly on your machine. This is simpler and the recommended approach for most users.

Which image should I use?

Currently we provide three different images, which can be downlaoded directly from Docker Hub:

  • zhinst/labone:<VERSION>-webserver: runs only the LabOne Web Server.
  • zhinst/labone:<VERSION>-dataserver: runs only the LabOne Data Server.
  • zhinst/labone:<VERSION>-full: runs both the LabOne Web Server and Data Server within a single container.

If you are using docker compose to run LabOne together with other applications, we recommend to run one container with the Web Server and one with the Data Server. If instead you are using docker directly, use the combined image instead.

When a new LabOne is released, a new version of each image is released as well. You can see the full list of available images on Docker Hub.

The sources for the containers are available on GithHub.

Examples

LabOne with Jupyter

This is an example of a docker compose with three containers:

  • One container runs the LabOne Web Server
  • One container runs the LabOne Data Server
  • One container runs a Jupyter Notebook web server 
    services:
  labone-web-server:
    image: zhinst/labone:25.1-webserver
    network_mode: "host"
  labone-data-server:
    image: zhinst/labone:25.1-dataserver
    network_mode: "host"
  jupyter-notebook:
    image: jupyter/minimal-notebook
    network_mode: "host"
    command: /bin/bash -c "pip install laboneq && start-notebook.py"
    You can start the services using docker compose up, then access the notebook at http://127.0.0.1:8888.

Important

By default, files written inside a Docker container are deleted when the container is stopped. Make sure to backup the notebooks you create in Jupyter!

Limitations

When using the LabOne Docker image you should watch out for the following limitations:

  • The LabOne Docker image can be executed only with the host networking mode. Other networking modes are not supported.
  • We don't offer support for running the LabOne Docker image on Windows or MacOS.
  • USB connections may not be visible within the Docker container. We recommend using Ethernet connections when using the LabOne Docker image.