TrizTech/ohif-viewer
17
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix/migration 3p11 (#5370)

Browse Source
This commit is contained in:
Alireza authored and GitHub committed 2025-08-28 12:57:45 -04:00
1 parent df0593aac9
commit 6a1838bf0d
391 files changed
+2322 -215
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

platform/docs/versioned_docs/version-3.11/deployment/docker/docker.md
+212
View File
@@ -0,0 +1,212 @@
---
sidebar_position: 4
title: Docker Deployment
summary: Comprehensive guide for deploying OHIF Viewer using Docker, covering pre-built images from Docker Hub, custom image building, configuration options through build arguments and environment variables, and runtime container management.
---
# Docker
The OHIF source code provides a [Dockerfile](https://github.com/OHIF/Viewers/blob/master/Dockerfile) to create and run a Docker image that containerizes an [nginx](https://www.nginx.com/) web server serving the OHIF Viewer.
:::info
This Dockerfile is the same used to generate the [OHIF image(s) on Docker Hub](https://hub.docker.com/r/ohif/app/tags).
:::
## 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](../../development/getting-started.md#branches).)
```sh
# 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](https://hub.docker.com/r/ohif/app/tags?page=1&name=latest) and [dev](https://hub.docker.com/r/ohif/app/tags?page=1&name=beta) images all in Docker Hub.
:::
### Prerequisites
The machine on which to build and run the Docker container must have:
1. All of the [requirements](../build-for-production.md#build-for-production) for building a production version of OHIF.
2. A checked out branch of the OHIF Viewer.
3. [Docker](https://docs.docker.com/get-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](../../platform/extensions/modules/data-source.md).
:::
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:
```sh
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:
```sh
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:
```sh
docker build . --build-arg PUBLIC_URL=/ohif/
```
- Set a custom app configuration:
```sh
docker build . --build-arg APP_CONFIG=config/kheops.js
```
- Specify a port:
```sh
docker build . --build-arg PORT=6000
```
- Combine multiple arguments:
```sh
docker build . --build-arg PUBLIC_URL=/ohif/ --build-arg APP_CONFIG=config/kheops.js --build-arg PORT=6000
```
:::info 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.
```sh
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`:
```sh
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:
```sh
docker build . --build-arg PORT=8080
```
then you can run the container with the following command:
```sh
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](#build-default)**: Set the default configuration file during the build process.
2. **[Volume Mounting](#volume-mounting)**: Mount a local configuration file into the container.
3. **[Environment Variable](#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:
```sh
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:
```sh
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:
```sh
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](https://stackoverflow.com/questions/46491061/shortcut-for-joining-two-lines) and [Notepad++](https://superuser.com/questions/518229/how-do-i-remove-linebreaks-in-notepad) offer "Join Lines" commands to help with this.
- If both the [Volume Mounting](#volume-mounting) and [Environment Variable](#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.
platform/docs/versioned_docs/version-3.11/deployment/docker/ssl.md
+128
View File
@@ -0,0 +1,128 @@
---
sidebar_position: 2
title: SSL Configuration for Docker
summary: Guide to configuring SSL for OHIF Viewer in Docker deployments, including environment variable setup, certificate mounting, permissions management, and instructions for both CA-signed and self-signed certificate implementation.
---
# SSL
:::caution
We make no claims or guarantees regarding this section concerning security. If in doubt, enlist the help of an expert and conduct proper audits.
:::
If OHIF is not deployed over SSL, this means information transferred to/from OHIF is not encrypted. Consideration must be given as to whether OHIF should be deployed in a secure context over SSL.
### Specifying the SSL Port, Certificate and Private Key
For convenience, the [built Docker image](#building-the-docker-image) can be run over SSL by
- setting the `{SSL_PORT}` environment variable
- volume mounting the SSL certificate
- volume mounting the SSL private key
:::info
The volume mounted SSL certificate and private key are mapped to the [`ssl_certificate`](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) and [`ssl_certificate_key`](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate_key) `nginx` directives respectively.
:::
Similar to the [`nginx` listen port](#configuring-the-nginx-listen-port), the `{SSL_PORT}` environment variable is the internal port that `nginx` listens on to serve the OHIF web server over SSL and has to be likewise published via the `-p` switch.
The following is an example command running the Docker container over SSL. Note that depending on the version of Docker, an absolute path to the certificate and private key files might be required.
```sh
docker run -d -e SSL_PORT=443 -p 3003:443/tcp -v /path/to/certificate:/etc/ssl/certs/ssl-certificate.crt -v /path/to/private/key:/etc/ssl/private/ssl-private-key.key --name ohif-viewer-container ohif-viewer-image
```
:::caution
The above deploys OHIF over SSL using `nginx`'s default SSL configuration. For further OHIF server hardening and security configuration, consider enlisting an expert and then editing OHIF's `nginx` [SSL template configuration file](https://github.com/OHIF/Viewers/blob/8a8ae237d26faf123abeb073cbf0cd426c3e9ef2/.docker/Viewer-v3.x/default.ssl.conf.template) with further [security settings](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) and [tweaks](http://nginx.org/en/docs/http/configuring_https_servers.html) and then [build a new Docker image](#building-the-docker-image) from there.
:::
:::caution
The private key is a secure entity and should have restricted access. Keep it safe!
:::
:::caution
The presence of the `{SSL_PORT}` environment variable is used to trigger to deploy over SSL as opposed to HTTP. If `{SSL_PORT}` is NOT defined, then HTTP is used even if the certificate and private key volumes are mounted.
:::
:::tip
The read and write permissions of the source, mounted volumes are preserved in the Docker container. The volume mounted certificate and private key require read permission.
One way to ensure both are readable is to issue the following on the host system terminal prior to running the Docker container and mounting the certificate and private key volumes.
```sh
sudo chmod 644 /path/to/certificate /path/to/private/key
```
:::
:::tip
The SSL certificate and private key can be either [CA issued](#ca-signed-certificates) or [self-signed](#self-signed-certificates).
:::
### CA Signed Certificates
According to [SSL.com](https://www.ssl.com/faqs/what-is-a-certificate-authority/), a global certificate authority (CA) is a trusted authority and organization that guarantees the identity of other, third-party entities and guarantees the integrity of the electronic information (e.g. web site data) those third-party entities provide and deliver.
There are many globally trusted CAs. Below is a non-exhaustive list of some CAs including links to some documentation for creating and installing certificates and keys from those authorities to be used with `nginx`.
- [GoDaddy](https://ca.godaddy.com/help/nginx-install-a-certificate-6722)
- [Let's Encrypt](https://www.nginx.com/blog/using-free-ssltls-certificates-from-lets-encrypt-with-nginx/)
- [digicert](https://www.digicert.com/kb/csr-ssl-installation/nginx-openssl.htm)
### Self-Signed Certificates
According to [Entrust](https://www.entrust.com/resources/faq/what-is-a-self-signed-certificate), a self-signed certificate is one that is NOT signed by a trusted, public [CA authority](#ca-signed-certificates), but instead (typically) signed by the developer or individual or organization responsible for a web site.
Browsers will treat self-signed certificates as not secure because the signer is not publicly recognized and trusted. When visiting a site encrypted with a self-signed certificate, the browser will present a screen similar to the following warning about the potential risk.
![Self-signed certificate warning](../../assets/img/self-signed-cert-warning.png)
For a self-signed certificate this is normal and expected. Clicking the `Advanced` button displays further information as well as a link for proceeding to site that the certificate is encrypting.
![Self-signed certificate warning](../../assets/img/self-signed-cert-advanced-warning.png)
Self-signed certificates might be appropriate for testing or perhaps deploying a site within an organization's internal LAN. In any case, consult an expert prior to deploying OHIF over SSL.
:::tip
A self-signed certificate can be generated using [`openssl`](https://www.openssl.org/) on the command line.
:::
To create a self-signed certificate:
1. Open a command prompt.
2. Issue the following command:
```sh
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /desired/key/directory/self-signed-private.key -out /desired/cert/directory/self-signed.crt
```
The chart below describes each of the items in the command.
|Command Item|Description|
|------------|-----------|
|sudo|temporarily grant access as the root/super user to run the `openssl` command|
|openssl|the command line tool for creating and managing certificates and keys|
|req|this together with the subsequent `-x509` indicates to request to generate a self-signed certificate|
|-x509|this together with the `req` indicates to request to generate a self-signed certificate|
|-nodes|skip the option to secure the certificate with a passphrase; this allows `nginx` to start up with without intervention to enter a passphrase each time|
|-days 365|the number of days the certificate will be valid for|
|-newkey rsa:2048|create the a new certificate and key together and make an RSA key that is 2048 bits long|
|-keyout|the path and file name where the private key will be written to|
|-out|the path and file name where the certificate will be written to|
3. Answer the prompts that follow. The table below lists the various prompts. The default value for each prompt is shown within the square brackets. The most important prompt is `Common Name (e.g. server FQDN or YOUR name)`. For this enter the IP address of the OHIF server being secured.
|Prompt|
|------|
|Country Name (2 letter code) [AU]|
|State or Province Name (full name) [Some-State]|
|Locality Name (eg, city) []|
|Organization Name (eg, company) [Internet Widgets Pty Ltd]|
|Organizational Unit Name (eg, section) []|
|Common Name (e.g. server FQDN or YOUR name) []|
|Email Address []|
4. Once completed, the self-signed certificate and private key will be in the locations specified by the `-keyout` and `-out` flags and can be [volume mounted](#specifying-the-ssl-port-certificate-and-private-key) accordingly to the OHIF Docker container.
:::tip
Windows' users can access `openssl` using [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/).
:::