WAD-QC Installation

Pre-installation requirements

To install the WAD-QC software you need to have a Linux OS installed. WAD-QC installation scripts for recent Ubuntu en CentOS (RedHat) Linux distributions are provided. Ubuntu 20.04 or 22.04 are the recommended distributions for WAD-QC 2.0. In case you only have Windows OS available, we suggest the use of a virtual machine (e.g. VirtualBox, VM-Ware) to run a Linux OS inside a Windows computer; for development WSL on Windows10 can be used.

The installation will claim a space in the home partition; for installation, a minimal free space of 1 GB is required. Because all databases will also be stored on the home partition, a large amount of free space (20-100GB) in the home partition is recommended.

WAD-QC uses the following software packages:

• python (supported version is python 3.x)
• Orthanc
• PostgreSQL

and will download python packages from pypi.org

Installation

Installation in a default configuration is automatic using the provided wad_setup installer. It may also be installed manually.

If you already have Orthanc running on your system for another service, do not use the installer, but use manual installation. In that case installation will not be straightforward, as you have to generate needed databases by hand, and you might need to tweak some port settings. Running two PostgreSQL installations side-by-side is supported in the recipes (but you have to fill out the details yourself), but running two Orthanc instances is not supported yet.

wad_setup.zip

• The installer scripts and all files required for a manual installation can be found in the wad_setup.zip file. You can download wad_setup.zip on the Downloads page.
• If you want to create an up-to-date wad_setup.zip from source code, clone or download the wadqc repository and run the following commands in the root folder of the cloned wadqc repository:

  #!bash
  python setup.py bdist_wheel
  ln -s ../dist wad_setup/
  zip -r wad_setup.zip wad_setup
  

Using the installer on Ubuntu 18.04LTS

wad_setup.py is a python script to perform an installation according to a recipe: a json file that specifies what installation steps to take. Several recipes are provided for Ubuntu, covering installation for production and for development. The recipes take care of installing required packages from the standard repositories and therefore the user that runs the installer needs to be added to the sudo group. If you want to revoke these privileges after installation, see the section "Restrict privileges of wadqc" in Security.

If the non-root user (e.g. "wadqc") that will install and run WAD-QC does not exist yet, or is not part of the sudo group, fix that first:

1. create a non-root user, e.g. "wadqc"
2. sudo adduser wadqc
3. sudo adduser wadqc sudo
4. logout current user and login as wadqc user

If you need to access internet through a proxy, see the Troubleshooting for installation on how to set it up. If you have an LDAP controlled system, see Troubleshooting for installation for additional help.

For a production installation on Ubuntu 18.04LTS do the following as the intended non-root user:

0. Ubuntu server only: install unzip using the command sudo apt install unzip
1. Download the wad_setup.zip from the Downloads section; you can use wget, e.g. wget https://bitbucket.org/MedPhysNL/wadqc/downloads/wad_setup_2.0.12.zip
2. unzip the wad_setup zipfile in the home folder of the non-root user that will run the WAD-QC server: e.g. unzip wad_setup_2.0.12.zip
3. cd wad_setup
4. optional but highly recommended for a production server: change default passwords in recipe file (see Security)
5. ./wad_setup.sh -r recipes/Lin64_Ubuntu1804_apt_virt.json

Note that WAD-QC is installed in a virtual environment for python, to separate all python packages from the system.

Manual installation steps for Ubuntu 18.04LTS

If for whatever reason you do not want to use the installer, you can also manually install WAD-QC.

It is assumed that:

• PostgreSQL and Orthanc are already installed
• pg_config and Orthanc can be found in the user's PATH.
• If either PostgreSQL or Orthanc is installed from the standard Ubuntu repositories, the automatically added system services should be disabled before the steps below are performed. That also means that those services are no longer accessible for other servers running on the system. If you need to have PostgreSQL accessible for other services on your system then you need to manually create the databases for WAD-QC and for Orthanc in the existing PostgreSQL server (which is not covered in this document).
• If a proxy is needed, you have set it up already.
• You have created a dedicated wadqc user with sudo rights

The following steps are for a python3 installation in a virtualenv named wad2env3. To manually create a virtualenv, consult the Glossary. Do not use sudo for the pip3 commands below! Run the steps below as the wadqc user.

1. activate the virtualenv: workon wad2env3
2. unzip wad_setup.zip in the home folder of the non-root user that will run the WAD-QC server
3. sudo apt install -y libpq5 curl libpq-dev python3-pip python3-dev tesseract-ocr tesseract-ocr-eng
4. pip3 install --upgrade pip jsmin simplejson requests
5. python3 wad_setup/scripts/folders_settings.py --root ~/WADROOT --wadqcdb_pass waddemo --orthancdb_pass waddemo --orthancweb_pass waddemo
6. pip3 install --upgrade dist/wad_qc-<version>-py2.py3-none-any.whl
7. python3 wad_setup/scripts/database_setup.py --root ~/WADROOT --create_postgresql_datadir --create_databases --initialize_wadqc
8. pip3 install --upgrade numpy scipy pillow matplotlib selectors34 pyocr
9. close the command line and start a new one (the changed environment variables PATH and WADROOT should be activated)
10. start all services needed for WAD-QC: wadservices -c start

Using the installer on CentOS7

Installer was tested with a CentOS7 "minimal install" with "standard system security profile" chosen during installation.

wad_setup.py is a python script to perform an installation according to a recipe: a json file that specifies what installation steps to take. Several recipes are provided for Ubuntu, covering installation for production and for development. The recipes take care of installing required packages from the standard repositories and therefore the user that runs the installer needs to be added to the sudo group.

Pre-installation

If the non-root user (e.g. "wadqc") that will install and run WAD-QC does not exist yet, or is not part of the sudo group, fix that first:

1. create a non-root user, e.g. "wadqc"
2. sudo adduser wadqc
3. sudo usermod -aG wheel wadqc
4. logout current user and login as wadqc user

If you want to revoke these privileges after installation, see the section "Restrict privileges of wadqc" in Security. If you need to access internet through a proxy, see the Troubleshooting for installation on how to set it up. If you have an LDAP controlled system, see Troubleshooting for installation for additional help.

For CentOS7 the SE-Linux mode has to be disabled because various services will run as a regular user. Furthermore some additional software packages that facilitate the installation itself need to be installed manually before the installer can be started.

Switch off SE-Linux permanently (starting next reboot): edit /etc/selinux/config and change SELINUX=enforcing to SELINUX=disabled

sudo nano /etc/selinux/config

Then issue sudo setenforce 0 to change current SE-Linux mode to "permissive" (alternatively, you may perform a reboot)

Install some tools to get and unzip wad_setup.zip

sudo yum -y install wget unzip

Installation

Download the wad_setup.zip from the Downloads section. You can use wget, e.g. wget https://bitbucket.org/MedPhysNL/wadqc/downloads/wad_setup_2.0.12.zip

Then unzip and run the installer:

1. unzip wad_setup_2.0.12.zip
2. cd wad_setup
3. optional but highly recommended for a production server: change default passwords in recipe file (see Security)
4. Start the installer, e.g. ./wad_setup.sh -r recipes/Lin64_CentOS7_yum_virt.json

Note that WAD-QC is installed in a virtual environment for python, to separate all python packages from the system.

Known issues for CentOS7

• postgres /var/run permissions
  • solved with pre-service wadpostgresql-permissions that sets permissions wad:war for /var/run/postgres and /var/log/postgres
  • to upgrade postgresql stop both wadpostgresql and wadpostgresql-permissions services.

Installation on Debian 9 and Debian 10

Just follow the installation instructions for Ubuntu18. In particular, use the installer with recipe Lin64_Ubuntu1804_apt_virt.json

Installation on Windows 10, using WSL

On Windows 10, the Windows Subsystem For Linux (WSL) can be used to set-up a Linux environment on Windows. WSL resembles running Linux in a docker container. As such, Ubuntu 18.04 can be installed in WSL, and then WAD-QC can be installed as well. As WSL is still in development, it is not recommended to run WAD-QC in WSL for production.

After preparing the Ubuntu 18.04 installation, just follow the installation instructions for Ubuntu 18.04 above, but use the installer recipe WSL_Ubuntu1804_apt_virt_nginx.json.

Support for jpeg compressed dicom

When encountering errors like these in your module logs:

Exception:
Traceback (most recent call last):
 File "/home/wadqc/Envs/wad2env3/lib/python3.6/site-packages/pydicom/pixel_data_handlers/pillow_handler.py", line 197, in get_pixeldata
   decompressed_image = Image.open(fio)
 File "/home/wadqc/Envs/wad2env3/lib/python3.6/site-packages/PIL/Image.py", line 2705, in open
   % (filename if filename else fp))
OSError: cannot identify image file <_io.BytesIO object at 0x7f6011870af0>

sudo apt update
mkdir /tmp/gdcm; cd /tmp/gdcm
wget -O gdcm-3.0.4.tar.gz https://sourceforge.net/projects/gdcm/files/gdcm%203.x/GDCM%203.0.4/gdcm-3.0.4.tar.gz/download
tar xzvf gdcm-3.0.4.tar.gz
mkdir gdcm-build
cd gdcm-build
sudo apt install cmake cmake-curses-gui g++ swig xsltproc libxslt1-dev docbook-xsl docbook-xsl-ns
cmake ../gdcm-3.0.4
ccmake ../gdcm-3.0.4
   GDCM_BUILD_SHARED_LIBS=ON
   GDCM_WRAP_PYTHON=ON
   [c] -> configure (repeat number of times until nothing changes)
   [g] -> generate and exit
make
cp bin/_gdcmswig.so bin/*.py ~/Envs/wad2env3/lib/python3.6/site-packages/
sudo make install
sudo ldconfig