How to compile Orthanc from source code on Ubuntu Server 20.04 LTS

[LHammonds]

------------- WORK-IN-PROGRESS -------------
NOTE: I have not yet done this...still documenting all the steps prior to actually doing it since there are no specific steps for Ubuntu 20.04

Space Requirements for Compiling (where it is compiled):
* At least 2 GB free in /root

Space Requirements for DICOM Router (where it is installed):
* Around 30 MB (log size not included)

Code: Select all

du -sh /usr/local/sbin/Orthanc /usr/local/share/orthanc /usr/local/bin/OrthancRecoverCompressedFile /usr/local/share/doc/orthanc /usr/local/include/orthanc

Install the prerequisites (listed in alphabetical order):

Code: Select all

sudo apt install build-essential cmake doxygen libboost-all-dev libcharls-dev libcurl4-openssl-dev libdcmtk-dev libgtest-dev libjpeg-dev libjsoncpp-dev liblua5.3-dev libpng-dev libpugixml-dev libsqlite3-dev libssl-dev libwrap0-dev mercurial uuid-dev zlib1g-dev

The following should already be installed on Ubuntu 20.04:

Code: Select all

unzip
python3
locales

Switch to the root user and create the default location for the source code and build:

Code: Select all

sudo su
mkdir -p ~/Orthanc/Build
mkdir -p ~/Orthanc/OrthancServer/ThirdPartyDownloads

Get the latest version of Orthanc from its download page (1.8.0 at the time of this writing).

Code: Select all

wget https://www.orthanc-server.com/downloads/get.php?path=/orthanc/Orthanc-1.8.0.tar.gz -O ~/Orthanc/Orthanc-1.8.0.tar.gz
tar -xzvf ~/Orthanc/Orthanc-1.8.0.tar.gz -C ~/Orthanc --strip-components=1
rm ~/Orthanc/Orthanc-1.8.0.tar.gz
cd ~/Orthanc

Optional - After the 1st time you compile (with auto-download enabled), it will download the following files. The next time you compile, it will not have to download them from the Internet. And if you copy them to a fresh server and compile for the 1st time, it will not need to access the Internet if it finds them already there.

Code: Select all

ls ~/Orthanc/OrthancServer/ThirdPartyDownloads/
boost_1_69_0_bcpdigest-1.5.6.tar.gz
civetweb-1.12-fixed.tar.gz
curl-7.64.0.tar.gz
dcmtk-3.6.5.tar.gz
e2fsprogs-1.44.5.tar.gz
jpegsrc.v9c.tar.gz
jsoncpp-1.8.4.tar.gz
libiconv-1.15.tar.gz
libpng-1.6.36.tar.gz
lua-5.3.5.tar.gz
openssl-1.1.1g.tar.gz
pugixml-1.9.tar.gz
sqlite-amalgamation-3270100.zip
zlib-1.2.11.tar.gz

Compile the source code:

Code: Select all

cd ~/Orthanc/Build
cmake -DSTATIC_BUILD=ON -DALLOW_DOWNLOADS=ON -DUSE_SYSTEM_CIVETWEB=OFF -DUSE_GOOGLE_TEST_DEBIAN_PACKAGE=ON -DDCMTK_LIBRARIES=dcmjpls -DCMAKE_BUILD_TYPE=Release ../OrthancServer/
make
make doc
make install

The install copies files to the following locations:

Code: Select all

/usr/local/sbin/Orthanc
/usr/local/share/orthanc/plugins/
/usr/local/bin/OrthancRecoverCompressedFile
/usr/local/share/doc/orthanc/OrthancPlugin/
/usr/local/include/orthanc/OrthancCDatabasePlugin.h
/usr/local/include/orthanc/OrthancCPlugin.h

[LHammonds]

Configuration

The goal I am trying to achieve is an installation very similar to how Orthanc is installed from the Debian repository (apt install orthanc)...but with systemd as the service manager rather than init.d.

Create the Orthanc user and group:

Code: Select all

mkdir -p /var/lib/orthanc/db-v6
useradd --home /var/lib/orthanc --comment 'Orthanc Administrator' --user-group orthanc
chown --recursive orthanc:orthanc /var/lib/orthanc
chmod 775 /var/lib/orthanc
chmod 755 /var/lib/orthanc/db-v6

Once compiled and installed, we now need to generate a default configuration file and folders.

Code: Select all

chown --recursive orthanc:orthanc /usr/local/share/orthanc
mkdir -p /var/log/orthanc
chown orthanc:orthanc /var/log/orthanc
chmod 775 /var/log/orthanc
mkdir -p /etc/orthanc
chown orthanc:orthanc /etc/orthanc
chmod 775 /etc/orthanc
Orthanc --config=/etc/orthanc/orthanc.json
chown orthanc:orthanc /etc/orthanc/*.json
chmod 664 /etc/orthanc/*.json

Edit the configuration file and change the following settings (vi /etc/orthanc/orthanc.json):

Code: Select all

  "Name" : "srv-dicom1",
  "StorageDirectory" : "/var/lib/orthanc/db-v6",
  "IndexDirectory" : "/var/lib/orthanc/db-v6",
  "Plugins" : [
    "/usr/local/share/orthanc/plugins"
  ],
  "DicomAet" : "SRVDICOM1",
  "RemoteAccessAllowed" : true,
     "AuthenticationEnabled" : true,
  "RegisteredUsers" : {
    "myadminid" : "myadminpass"
  },
  "DicomModalities" : {
    "PACSProd" : [ "PACSPROD", "192.168.1.200", 104],

Systemd

Code: Select all

touch /lib/systemd/system/orthanc.service
chown root:root /lib/systemd/system/orthanc.service
chmod 644 /lib/systemd/system/orthanc.service
vi /lib/systemd/system/orthanc.service

Code: Select all

[Unit]
Description=Orthanc DICOM Service
After=network.target
After=network-online.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=orthanc
ExecStart=/usr/local/sbin/Orthanc --logdir=/var/log/orthanc/ /etc/orthanc/

[Install]
WantedBy=multi-user.target

Enable the service (which creates a link to /etc/systemd/system)

Code: Select all

sudo systemctl enable orthanc

Start the service and check the log (press CTRL+C to stop the realtime observation of the log):

Code: Select all

sudo systemctl start orthanc
sudo tail -f /var/log/orthanc/Orthanc.log

[LHammonds]

Transcoding to Jpeg2000 Lossless

EDIT: This section has been aborted. It turns out that even if I compress the dicom to match the target system, the target system will re-encode no matter what so this would be a waste of time for my server and thus, just need to route the studies untouched.

At my location, our destination PACS system stores all incoming images in Jpeg 2000 lessless format. To help alleviate that extra step and save some time on the transmission of the large images over the wide-area network, Orthanc needs to be configured to handle. With version 1.7.0 and above, it has a built-in method to automatically transcode while injesting.

Our source images from modalities are Implicit VR Little Endian and the UID is 1.2.840.10008.1.2
The target Jpeg 2000 Lossless UID will be 1.2.840.10008.1.2.4.90

Related manual pages: Transcoding of DICOM files, Registry of DICOM UIDs

Regarding UID, the DICOM rule is the following: If using lossless (non-destructive) compression, the SOP Instance UID tag *can* stay the same after transcoding. On the other hand, If using lossy (destructive) compression, the SOP Instance UID tag *must* change (for medical traceability, as the information has changed).

Self Note: Need to find a link to the official rule that the above quote is referencing.

Settings to be applied in the orthanc.json:

Code: Select all

  //** 1.2.840.10008.1.2 = Implicit VR Little Endian (Default)
  //"IngestTranscoding" : "1.2.840.10008.1.2",

  //** 1.2.840.10008.1.2.4.90 = JPEG 2000 Compression (Lossless)
  "IngestTranscoding" : "1.2.840.10008.1.2.4.90",
  "DicomLossyTranscodingQuality" : 100

[LHammonds]

For a production environment, it might be better to create a .deb install file on a non-production "compiling machine" and transfer that .deb file to the target server and install the .deb file. The main item to consider is that the compiling machine and production server are running the same OS (e.g. Ubuntu Server 20.04 LTS)

Make sure you install the compilation package:

Code: Select all

sudo apt install checkinstall

On the compiling machine, run the below command but substitute your own settings for maintainer and pkgsource. Run this right after the "make" and "make doc" commands.

It will ask you a few questions, answer however you want. I set my description to "Lightweight, RESTful DICOM server for medical imaging"

Code: Select all

checkinstall -D --install=no --maintainer="LHammonds" --pkgsource="https://hammondslegacy.com" --pkgname="orthanc-loc" --pkgversion="1.8.0" --pkgrelease="SNAPSHOT" --arch="$(dpkg --print-architecture)" --pkglicense="GPLv3" --requires="adduser,dcmtk,locales,lsb-base,libboost-filesystem1.71.0,libboost-locale1.71.0,libboost-regex1.71.0-icu66,libboost-thread1.71.0,libc6 \(\>= 2.31\),libcurl4 \(\>= 7.68.0\),libdcmtk14,libgcc-s1 \(\>= 10.2.0\),libjpeg8 \(\>= 8c\),libjsoncpp1 \(\>= 1.7.4\),liblua5.1-0,libpng16-16 \(\>= 1.6.37-2\),libpugixml1v5 \(\>= 1.10-1\),libsqlite3-0 \(\>= 3.31.1\),libssl1.1 \(\>= 1.1.1\),libstdc++6 \(\>= 10.2.0\),libuuid1 \(\>= 2.34\),zlib1g \(\>= 1:1.2.11\)" --provides="orthanc"

NOTE: I copied the requirements from what is listed for Orthanc 1.5.8 in the Official Ubuntu repository. They might not be accurate for 1.8.0 but have yet to see where to find that info so I simply set the minimum version to what I see installed on Ubuntu Server 20.04.1 LTS at the time I compiled. The command below is how it looks if you use the exact requirements for 1.5.8 in the Official Ubuntu repository:

Code: Select all

checkinstall -D --install=no --maintainer="LHammonds" --pkgsource="https://hammondslegacy.com" --pkgname="orthanc" --pkgversion="1.8.0" --pkgrelease="SNAPSHOT" --arch="$(dpkg --print-architecture)" --pkglicense="GPLv3" --requires="adduser,dcmtk,locales,lsb-base,libboost-filesystem1.71.0,libboost-locale1.71.0,libboost-regex1.71.0-icu66,libboost-thread1.71.0,libc6 \(\>= 2.28\),libcurl4 \(\>= 7.16.2\),libdcmtk14,libgcc-s1 \(\>= 3.0\),libjpeg8 \(\>= 8c\),libjsoncpp1 \(\>= 1.7.4\),liblua5.1-0,libpng16-16 \(\>= 1.6.2-1\),libpugixml1v5 \(\>= 1.6\),libsqlite3-0 \(\>= 3.7.3\),libssl1.1 \(\>= 1.1.0\),libstdc++6 \(\>= 9\),libuuid1 \(\>= 2.16\),zlib1g \(\>= 1:1.2.0\)" --provides="orthanc"

The end-result file will be something like this:

Code: Select all

-rw-r--r-- 1 root root 7092588 Oct 23 16:56 /root/Orthanc/Build/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb

You can look at the package information with this command:

Code: Select all

dpkg-deb --info ~/Orthanc/Build/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb

Code: Select all

 new Debian package, version 2.0.
 size 7093120 bytes: control archive=640 bytes.
       0 bytes,     0 lines      conffiles
     691 bytes,    11 lines      control
 Package: orthanc-loc
 Priority: extra
 Section: checkinstall
 Installed-Size: 26068
 Maintainer: LHammonds
 Architecture: amd64
 Version: 1.8.0-SNAPSHOT
 Depends: adduser,dcmtk,locales,lsb-base,libboost-filesystem1.71.0,libboost-locale1.71.0,libboost-regex1.71.0-icu66,libboost-thread1.71.0,libc6 (>= 2.31),libcurl4 (>= 7.68.0),libdcmtk14,libgcc-s1 (>= 10.2.0),libjpeg8 (>= 8c),libjsoncpp1 (>= 1.7.4),liblua5.1-0,libpng16-16 (>= 1.6.37-2),libpugixml1v5 (>= 1.10-1),libsqlite3-0 (>= 3.31.1),libssl1.1 (>= 1.1.1),libstdc++6 (>= 10.2.0),libuuid1 (>= 2.34),zlib1g (>= 1:1.2.11)
 Provides: orthanc
 Description: Lightweight, RESTful DICOM server for medical imaging

Transfer the generated .deb file to the new Orthanc server.

Code: Select all

scp ~/Orthanc/Build/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb administrator@192.168.1.31:/tmp/.
scp ~/Orthanc/Build/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb administrator@192.168.1.32:/tmp/.
scp ~/Orthanc/Build/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb administrator@192.168.1.33:/tmp/.

On the Orthanc server, install from the .deb package that was copied to it.

Code: Select all

sudo dpkg -i /tmp/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb

It will likely error out saying required dependencies are not installed. Example:

Code: Select all

Selecting previously unselected package orthanc.
(Reading database ... 110139 files and directories currently installed.)
Preparing to unpack .../orthanc_1.8.0-SNAPSHOT_amd64.deb ...
Unpacking orthanc (1.8.0-SNAPSHOT) ...
dpkg: dependency problems prevent configuration of orthanc:
 orthanc depends on dcmtk; however:
  Package dcmtk is not installed.
 orthanc depends on libboost-filesystem1.71.0; however:
  Package libboost-filesystem1.71.0 is not installed.
 orthanc depends on libboost-locale1.71.0; however:
  Package libboost-locale1.71.0 is not installed.
 orthanc depends on libboost-regex1.71.0-icu66; however:
  Package libboost-regex1.71.0-icu66 is not installed.
 orthanc depends on libboost-thread1.71.0; however:
  Package libboost-thread1.71.0 is not installed.
 orthanc depends on libdcmtk14; however:
  Package libdcmtk14 is not installed.
 orthanc depends on libjpeg8 (>= 8c); however:
  Package libjpeg8 is not installed.
 orthanc depends on libjsoncpp1 (>= 1.7.4); however:
  Package libjsoncpp1 is not installed.
 orthanc depends on liblua5.1-0; however:
  Package liblua5.1-0 is not installed.
 orthanc depends on libpugixml1v5 (>= 1.10-1); however:
  Package libpugixml1v5 is not installed.

dpkg: error processing package orthanc-loc (--install):
 dependency problems - leaving unconfigured
Errors were encountered while processing:
 orthanc-loc

After trying to install the .deb package, you can now run this command which will install the required packages and then install Orthanc:

Code: Select all

sudo apt-get -f install

You can see the destination folder (and files) by looking at the contents inside the .deb file with this command:

Code: Select all

sudo dpkg-deb --contents /tmp/orthanc-loc_1.8.0-SNAPSHOT_amd64.deb

It is the same destination locations as if compiled on this machine:

Code: Select all

/usr/local/sbin/Orthanc
/usr/local/share/orthanc/plugins/
/usr/local/bin/OrthancRecoverCompressedFile
/usr/local/share/doc/orthanc/OrthancPlugin/
/usr/local/include/orthanc/OrthancCDatabasePlugin.h
/usr/local/include/orthanc/OrthancCPlugin.h

To remove the manually installed package (such as prior to installing a newer version):

Code: Select all

sudo dpkg -r orthanc-loc

To remove the configuration files as well:

Code: Select all

sudo dpkg --purge orthanc-loc

[LHammonds]

Upgrade Procedure Using .DEB Package

1. Stop the service:

   Code: Select all

   sudo systemctl stop orthanc

2. Uninstall the package:

   Code: Select all

   sudo apt remove orthanc-loc

3. Install the new package:

   Code: Select all

   sudo dpkg -i /tmp/orthanc-loc_1.8.1-SNAPSHOT_amd64.deb

   NOTE: If the requirements changed, you might need to run this command to install the requirements (which will then install Orthanc)

   Code: Select all

   sudo apt-get -f install

4. If configuration changes need to be made such as adding new options, do so now.
5. Start the service:

   Code: Select all

   sudo systemctl start orthanc

6. Wait for a minute and check the status:

   Code: Select all

   systemctl status orthanc

7. Check the logs for problems:

   Code: Select all

   tail -n100 /var/log/orthanc/Orthanc.log