Docker

The OHIF source code provides a Dockerfile to create and run a Docker image that containerizes an nginx web server serving the OHIF Viewer.

info

This Dockerfile is the same used to generate the OHIF image(s) on Docker Hub.

Running the Docker Container with our pre-built images from Docker Hub

To run the Docker container, use the following command based on whether you're targeting a release or beta version. (Learn more about versioning here.)

#  beta version
docker run -d -p 3000:80 ohif/app:v3.10.0-beta.33

# release version
docker run -d -p 3000:80 ohif/app:v3.9.2

This will run the Docker container and serve the OHIF Viewer at http://localhost:3000. You can name the container anything you want by adding the --name flag (e.g., docker run -d -p 3000:80 --name ohif-viewer-container ohif/app:v3.10.0-beta.33).

Building the Docker Image From Source

tip

Building a Docker image comes in handy when OHIF has been customized (e.g. with custom extensions, modes, hanging protocols, etc.). For convenience, there are basic OHIF images built in Docker Hub. Find the latest release and dev images all in Docker Hub.

Prerequisites

The machine on which to build and run the Docker container must have:

1. All of the requirements for building a production version of OHIF.
2. A checked out branch of the OHIF Viewer.
3. Docker installed.

Building the Docker Image

info

In this tutorial, we will build the Docker image for the OHIF Viewer and OHIF server as defined in the default.js config which points to our server and our studies.

If you need the Viewer to show your own server studies, you need to build the viewer with a custom configuration that points to your server and your studies.

You can set build arguments to point to your custom configuration file. For more information on data sources, see here.

To build the Docker image from the terminal:

• Navigate to the OHIF Viewer code root directory (base of the monorepo).

• Run a basic Docker build command:

  docker build . -t ohif-viewer-image

  Note: The name ohif-viewer-image is an example. You can replace it with any name and tag of your choice by changing the -t value (e.g., -t my-image:latest). This naming is arbitrary for local Docker images.

• To customize the build, you can include optional build arguments to set defaults for the app configuration, public path, or port:

  docker build . -t ohif-viewer-image \
    --build-arg APP_CONFIG=config/e2e.js \
    --build-arg PUBLIC_URL=/ohif/ \
    --build-arg PORT=6000

Available Build Arguments (Optional)

You can use the following build arguments to customize the Docker image:

• APP_CONFIG: (Optional) Sets the default app configuration (e.g., config/e2e.js). This value can be overridden later by setting an environment variable (you can set it in the docker run command).
• PUBLIC_URL: (Optional) Specifies the public path for serving the OHIF Viewer (e.g., /ohif/). This value is baked into the build and cannot be changed without rebuilding the image.
• PORT: (Optional) Sets the application’s port.

Examples of Using Build Arguments

Here are examples of how to use the --build-arg option:

• Set the public path:

  docker build . --build-arg PUBLIC_URL=/ohif/

• Set a custom app configuration:

  docker build . --build-arg APP_CONFIG=config/kheops.js

• Specify a port:

  docker build . --build-arg PORT=6000

• Combine multiple arguments:

  docker build . --build-arg PUBLIC_URL=/ohif/ --build-arg APP_CONFIG=config/kheops.js --build-arg PORT=6000

PUBLIC_URL Explanation

The PUBLIC_URL build argument sets the public path for serving the OHIF Viewer. For example, using --build-arg PUBLIC_URL=/ohif/ will serve the worklist at http://host/ohif/ and the viewer at http://host/ohif/viewer. While the worklist is also accessible at http://host/, it redirects to the PUBLIC_URL.

---

Running the Docker Container

After building the Docker image, you can run it as a container using the following command. The name of the Docker image (ohif-viewer-image) is specified at the end, while the flags control various runtime settings.

docker run -d -p 3000:80/tcp --name ohif-viewer-container ohif-viewer-image

• -d: Runs the container in the background and prints the container ID.

• -p {host-port}:{nginx-port}/tcp: Maps the container's nginx port to a port on the host machine. For example, 3000:80 maps host port 3000 to container port 80.

• --name: Assigns an arbitrary name to the container for easy identification (e.g., ohif-viewer-container).

Configuring the nginx Listen Port

The nginx server uses the {PORT} environment variable to determine the listening port inside the container. By default, this is set to 80. You can override it during runtime or build:

Setting the Port at Runtime

Use the -e PORT={container-port} flag to set the listening port and publish it with -p. For example, the following command sets the container port to 8080 and maps it to host port 3000:

docker run -d -e PORT=8080 -p 3000:8080/tcp --name ohif-viewer-container ohif-viewer-image

Setting the Port During Build

To bake the port configuration into the Docker image, use the --build-arg PORT={container-port} flag when building the image:

docker build . --build-arg PORT=8080

then you can run the container with the following command:

docker run -d -p 3000:8080/tcp --name ohif-viewer-container ohif-viewer-image

---

Specifying the OHIF Configuration File

You can specify the OHIF configuration file for the container in three ways:

1. Build Default: Set the default configuration file during the build process.
2. Volume Mounting: Mount a local configuration file into the container.
3. Environment Variable: Pass the configuration file contents directly as an environment variable.

Build Default

Set the configuration file during the build process using the --build-arg APP_CONFIG={config-path} flag. For example:

docker build . --build-arg APP_CONFIG=config/kheops

---

Volume Mounting

To use a local configuration file, mount it as a volume during runtime. For example, to use a file located at /path/to/config/file.js, use the -v flag:

docker run -d -p 3000:80/tcp -v /path/to/config/file.js:/usr/share/nginx/html/app-config.js --name ohif-viewer-container ohif-viewer-image

tip

Ensure the path to the local configuration file is absolute, as some Docker versions require it.

---

Environment Variable

Alternatively, you can specify the configuration file contents directly as an environment variable (APP_CONFIG). This method is useful in environments like Google Cloud.

Important: The APP_CONFIG variable must contain the file's contents, not its file path. Use the cat command to read the file and pass its contents as the environment variable:

docker run -d -p 3000:80/tcp -e APP_CONFIG="$(cat /path/to/the/config/file)" --name ohif-viewer-container ohif-viewer-image

tip

• Remove single-line comments (//) from the configuration file to prevent issues when serving the file to the OHIF client.
• As an alternative to the cat command, you can convert the file to a single line and copy-paste it directly. Tools like Visual Studio Code and Notepad++ offer "Join Lines" commands to help with this.
• If both the Volume Mounting and Environment Variable methods are used, the Volume Mounting method takes precedence.

---

This rewrite improves readability by reorganizing information into smaller, clear sections and providing consistent formatting for examples and tips.