Ultrack Docker Image

This example shows how to use the Ultrack Docker image. The Docker image is a pre-configured environment that includes the Ultrack software and all its dependencies. The images are available on Docker Hub at royerlab/ultrack repository. You can also build the image from scratch (see the Running the Docker Image section).

In the following sections, we will discuss:

Running the Docker Image

To run the Ultrack Docker image, you can use the following command:

docker run -it --rm -v /path/to/your/data:/data royerlab/ultrack:0.6.1-cpu  # replace 6.0.1-cpu with the desired version and
                                                                            # variant (e.g., 6.0.1-cpu, 6.0.1-cuda11.8)

This command will start the Ultrack Docker image and mount the /path/to/your/data directory to the /data directory inside the container. Replace /path/to/your/data with the path to your data directory. Then, you can use the Ultrack CLI for your analysis.

Gurobi support

Gurobi is a commercial optimization solver used in Ultrack for solving optimization problems. To use Gurobi inside the Ultrack Docker image, you need a valid Web License Service (WLS) license. Once you have the license file (gurobi.lic), mount it to the /opt/gurobi/gurobi.lic directory inside the container. For example:

docker run -it --rm -v /path/to/your/data:/data \
       -v /path/to/your/gurobi.lic:/opt/gurobi/gurobi.lic \
       royerlab/ultrack:0.6.1-cpu

Check the Gurobi support by running:

ultrack check_gurobi

This should display the Gurobi license information if the license file is valid.

GPU support

The Ultrack Docker image supports GPU acceleration using CUDA. To use GPU support, you need a compatible NVIDIA GPU and the NVIDIA driver installed on your host machine. Include the –gpus all flag in the docker run command. For example:

docker run -it --rm -v /path/to/your/data:/data --gpus all \
       royerlab/ultrack:0.6.1-cuda11.8  # replace 6.0.1-cuda11.8 with the
                                        # desired version and variant

Running the Docker Image with Jupyter Notebook

You can run the Ultrack Docker image with a Jupyter Notebook server by forwarding the default Jupyter port (8888) to the host machine using -p 8888:8888. If the port is in use, use a different port (e.g., -p 8889:8888):

docker run -it --rm -v /path/to/your/data:/data -p 8888:8888 royerlab/ultrack:0.6.1-cpu

After starting the container, install the Jupyter Notebook server:

uv pip install --no-cache --system jupyterlab  # or simply `pip install jupyterlab`

Start the Jupyter Notebook server:

jupyter lab --ip=0.0.0.0 --allow-root  # ip=0.0.0.0 allows access from any IP address
                                       # allow-root allows running Jupyter as root (default user in container)

You will see a URL to access the Jupyter Notebook server in your browser. Use the Ultrack API to analyze your data.

(Optional) Building the Docker Image

To build the Ultrack Docker image from scratch, use the following command:

python3 docker/build_containers.py

This command requires an argument specifying the desired version and variant of the Ultrack Docker image. If not provided, the script lists all available versions and variants. For example, to build an image with basic CPU support:

python3 docker/build_containers.py cpu

You can then use the built image as described in the Running the Docker Image section.