VIEW installation

Requirements

Server-side requirements

Operating system

The application can run on any 64-bit Linux OS compatible with Docker Engine.

The recommended Linux operating systems are:

• Ubuntu 22.04 LTS or 24.04 LTS

• RHEL-based OS

Minimal hardware requirements

* Equivalent of 7th generation Intel i5 2.4 GHz CPU core.

The storage is used for software and temporary data cache. At least 50 GB of storage size is recommended.

Since the network bandwidth directly affects opening speed, we recommend at least 100 Mbit/s.

Client-side requirements

** To reach the best performance we recommend the use of Google Chrome.

Installation

Installation prerequisites

The installation requires Docker Engine installed on the operating system. For instructions on how to install Docker Engine see the official website: Install Docker Engine.

Installation procedure

Docker login

The ready-to-use Docker image of the system is available in the shared repository europe-west1-docker.pkg.dev/o3-cloud-internal/partner.

To authenticate to the repository, a Service account key will be provided via e-mail as a JSON file.

Copy the file on the target machine and execute the following command, by replacing the parameter KEY-FILE with the path to the provided JSON file:

cat {KEY-FILE} | sudo docker login -u _json_key --password-stdin europe-west1-docker.pkg.dev

Environment setup

After the Docker login, it's advisable to create an environment file and a docker-compose.yml file.

This facilitates easier control and deployment of the container. Alongside the YAML file, we recommend using an environment file to store variables that the docker-compose files will utilize. This approach allows for convenient modification of variable values in the environment file, which will automatically be reflected in the YAML files, as they can be configured to read from this environment file.

The environment file should be located in the same directory as the docker-compose.yml, and its name should start with a dot. Typically, we name it .env.

.env file

Below is an example of a .env file that can be used for VIEW installation. Please replace the value of the following variables with the appropriate one:

• COMPOSE_FILE: specify which docker-compose files should be read from this environment file.

• STORAGE: specify the path where the integrated storage will store all the DICOM files and images. Create the directory if it is not already present.

• PATHDC: specify where the docker-compose.yml file and the .env file are located.

• DB_IMAGE: specify the MySQL image to use. We also support MySQL 5.7, but we highly recommend using MySQL 8.0.

• DB_PASSWORD: specify the password for the DB 'root' user.

• TIMEZONE: specify the local timezone.

• VIEW_IMAGE: at the end of the line, instead of {X.Y.Z} fill in the designated VIEW image.

## This is an example of the enviroment file to store all the variables used by the docker-compose.yml and by the applications.
COMPOSE_FILE=docker-compose.yml     ## Specify which docker-compose files should be read from this environment file.  
STORAGE={pathToStorage}            ## Path where the integrated storage will store all the DICOM files and images. Create the directory if not already present. 
PATHDC={pathToDocker-ComposeFiles}  ## Location of the docker-compose.yml file and the .env file.
DB_IMAGE=mysql:8.0.34               ## MySQL image to use. We support also MySQL 5.7, but we highly recommend using MySQL 8.0.
DB_PASSWORD={dbPassword}            ## Password for the DB 'root' user.
TIMEZONE={timezone}                 ## Local timezone. 
DB_PASSWORD={dbPassword}            ## Password for the DB 'root' user.
TIMEZONE={timezone}                 ## Local timezone.

VIEW_IMAGE=europe-west1-docker.pkg.dev/o3-cloud-internal/partner/view:{X.Y.Z}  ## Replace {X.Y.Z} with the proper version of the VIEW system.

##The next line is a configuration option for MySQL database. Here is possible to define preferences for the data storage.
VARMYSQL=--sql_mode="STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,ALLOW_INVALID_DATES" --character_set_server=utf8 --collation_server=utf8_general_ci

##The lines below are the connection strings the application will use to connect to the database ('db' is the name of the container defined in the YAML file).
NGV_CONNECTION_STRING=driverClassName=com.mysql.cj.jdbc.Driver;jdbcUrl=jdbc:mysql://db:3306/public_view;username=root;password=${DB_PASSWORD}  

docker-compose.yml file

Below is a ready-to-use example of a docker-compose.yml file that can be used for VIEW installation. In it, every value that begins with a $ represents a variable stored in the environment file (no modifications are necessary).

version: '3.2'
services:
  db:
    image: ${DB_IMAGE}
    container_name: db
    restart: always
    env_file:
      - .env
    volumes:
      - "${STORAGE}/compose/db:/var/lib/mysql:rw"
    environment:
      - "MYSQL_ROOT_PASSWORD=${DB_PASSWORD}"
      - TZ=${TIMEZONE}
    command: mysqld ${VARMYSQL}
    healthcheck:
        test: ["CMD", "mysql", "-h", "db", "-u", "root", "-p${DB_PASSWORD}"]
        interval: 2s
        timeout: 10s
        retries: 5
    ports:
      - "3306:3306"
    ulimits:
      nproc: 65535
      nofile:
        soft: 26677
        hard: 46677
    networks:
      - o3net
      
  view:
    image: ${VIEW_IMAGE}
    container_name: view
    restart: always
    env_file:
      - .env
    volumes:
      - ${STORAGE}/compose/storage:/opt/storagePacs
      - ${STORAGE}/compose/view/shared-persist:/opt/ipv/shared-persist
      - ${STORAGE}/compose/view/log:/opt/ipv/log
    environment:
      - TZ=${TIMEZONE}
      - LOG_TO=FILE
      - NGV_CONNECTION_STRING=${NGV_CONNECTION_STRING}
    depends_on:
      db:
        condition: service_healthy
    ports:
      - 8181:8181
    networks:
      - o3net
      
networks:
  o3net:
    driver: bridge
    ipam:
      driver: default
      config:
      - subnet: 172.16.1.0/24

Once both files are finalized and ready, execute the following command within the directory where these files are located to start the database container:

sudo docker compose up -d db

Once the image is pulled from the repository and the container is running, execute the command that creates the VIEW schema:

sudo docker exec db mysql -u root -p${DB_PASSWORD} -e "create schema public_view";

If this process completes without any errors, the database should be ready for connections.

After the schema creation, it is possible to start all the other containers by executing the following command:

sudo docker compose up -d

Provided that all steps were executed correctly and the configuration is accurate, the container should start, and the application will run.

To access the application's interface and configure the system, see VIEW configuration.

Logs

If the containers aren't active or if the application interface is inaccessible, it indicates an issue has occurred.

To diagnose the problem, you can consult and analyze specific files found in the /{pathToStorage}/view/log directory, as defined in the volumes part of the YAML file.

Alternatively, the docker logs -f view command can be used to check the logs and gain insights into what might have gone wrong.

Updates

To update the application’s version simply substitute in the .env file the tag of the VIEW_IMAGEvariable with the new one and execute the following command:

sudo docker compose up -d