# HG changeset patch # User Sebastien Jodogne # Date 1478613071 -3600 # Node ID bd0fbf1f0143926a83e4b7c63efef86c09bbea10 # Parent 22b6ed6c9d5c9d17fb0a6bec0ea3d44052030e61 docker documentation diff -r 22b6ed6c9d5c -r bd0fbf1f0143 Sphinx/source/users/cookbook.rst --- a/Sphinx/source/users/cookbook.rst Sat Oct 22 22:26:39 2016 +0200 +++ b/Sphinx/source/users/cookbook.rst Tue Nov 08 14:51:11 2016 +0100 @@ -17,7 +17,7 @@ * :ref:`Compile Orthanc by yourself `. * `Download pre-compiled packages `__. -* `Use Docker `__. +* :ref:`Use Docker `. * External contributors are also maintaining `Vagrant VM for Orthanc `__. diff -r 22b6ed6c9d5c -r bd0fbf1f0143 Sphinx/source/users/docker.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/users/docker.rst Tue Nov 08 14:51:11 2016 +0100 @@ -0,0 +1,189 @@ +.. _docker: +.. highlight:: bash + + +Orthanc for Docker +================== + +.. contents:: + :depth: 3 + + +Introduction +------------ + +`Docker images `__ +for the Orthanc core and its official plugins are freely available on +the `DockerHub platform `__. The +source code of the corresponding Docker images is available on `GitHub +`__. + +*Note for CentOS users:* The Docker environment might be difficult to +configure on your platform. Hints are available on the `Orthanc Users +discussion group +`__. + + +Running the Orthanc core +------------------------ + +The following command will start the core of Orthanc, with all the +plugins disabled:: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc + +Once Orthanc is running, use Mozilla Firefox at URL +http://localhost:8042/ to interact with Orthanc. The default username +is ``orthanc`` and its password is ``orthanc``. + +The command above starts the mainline version of Orthanc, whose +development is in continuous progress. This gives you access to the +latest features. If more stability is required, you can select the +release of Orthanc to be run:: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc:1.1.0 + +Passing additional command-line options (e.g. to make Orthanc verbose) +can be done as follows (note the ``/etc/orthanc`` option that is +required for Orthanc to find its configuration files):: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc /etc/orthanc --verbose + + +Usage, with plugins enabled +--------------------------- + +The following command will run the mainline version of the Orthanc +core, together with its :ref:`Web viewer `, its +:ref:`PostgreSQL support `, its :ref:`DICOMweb +implementation `, and its :ref:`whole-slide imaging viewer +`:: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins + + +Fine-tuning the configuration +----------------------------- + +For security reasons, you should at least protect your instance of +Orthanc by changing this default user, in the ``RegisteredUsers`` +:ref:`configuration option `. You will also probably +need to fine-tune other parameters, notably the list of the DICOM +modalities Orthanc knows about. + +You can generate a custom configuration file for Orthanc as follows:: + + $ sudo docker run --rm --entrypoint=cat jodogne/orthanc /etc/orthanc/orthanc.json > /tmp/orthanc.json + +Then, edit the just-generated file ``/tmp/orthanc.json`` and restart +Orthanc with your updated configuration:: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc + + +Making the Orthanc database persistent +-------------------------------------- + +The filesystem of Docker containers is volatile (its content is +deleted once the container stops). You can make the Orthanc database +persistent by mapping the ``/var/lib/orthanc/db`` folder of the +container to some path in the filesystem of your Linux host, e.g.:: + + $ mkdir /tmp/orthanc-db + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc-db/:/var/lib/orthanc/db/ jodogne/orthanc:1.1.0 + + +Whole-slide imaging support +--------------------------- + +The ``orthanc-plugins`` image includes support for :ref:`microscopic +whole-slide imaging (WSI) `. For instance, the following command +will start the WSI viewer plugin transparently together with Orthanc:: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm --name orthanc-wsi jodogne/orthanc-plugins + +Note that we gave the name ``orthanc-wsi`` to this new Docker +container. Then, the Dicomizer command-line tool can be invoked as +follows:: + + $ sudo docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.tif:/tmp/Source.tif:ro jodogne/orthanc-plugins --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ /tmp/Source.tif + +This command needs a few explanations: + +* ``--link=orthanc-wsi:orthanc`` links the container running the + Dicomizer, to the Docker container running Orthanc that we started + just before. +* ``--entrypoint=OrthancWSIDicomizer`` specifies that the Dicomizer + must be run instead of the Orthanc server. +* ``-v /tmp/Source.tif:/tmp/Source.tif:ro`` maps the source image + ``/tmp/Source.tif`` on the host computer into the Orthanc container + as read-only file ``/tmp/Source.tif``. +* ``--orthanc=http://orthanc:8042/`` instructs the Dicomizer to push + images through the ``--link`` created above. +* ``--username=orthanc --password=orthanc`` correspond to the default + credentials of the ``orthanc-plugins`` image. + +Obviously, you are free to add all the options you wish (check out the +``--help`` flag to list these options). In particular, the +``--dataset`` option allows to specify DICOM tags, in the JSON file +format, so as to include them in the resulting DICOM series (the +option ``--sample-dataset`` prints a sample JSON file that has the +expected format). + +If you have a source image that is not a hierarchical TIFF, you must +instruct the Dicomizer to use `OpenSlide `__ to +decode it by adding the ``--openslide`` option:: + + $ sudo docker run -t -i --rm --link=orthanc-wsi:orthanc --entrypoint=OrthancWSIDicomizer -v /tmp/Source.svs:/tmp/Source.svs:ro jodogne/orthanc-plugins --username=orthanc --password=orthanc --orthanc=http://orthanc:8042/ --openslide=libopenslide.so /tmp/Source.svs + + +PostgreSQL and Orthanc inside Docker +------------------------------------ + +It is possible to run both Orthanc and PostgreSQL inside Docker. First, start the official PostgreSQL container:: + + $ sudo docker run --name some-postgres -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=pgpassword --rm postgres + +Open another shell, and create a database to host the Orthanc database:: + + $ sudo docker run -it --link some-postgres:postgres --rm postgres sh -c 'echo "CREATE DATABASE orthanc;" | exec psql -h "$POSTGRES_PORT_5432_TCP_ADDR" -p "$POSTGRES_PORT_5432_TCP_PORT" -U postgres' + +You will have to type the password (cf. the environment variable +``POSTGRES_PASSWORD`` above that it set to ``pgpassword``). Then, +retrieve the IP and the port of the PostgreSQL container, together +with the default Orthanc configuration file:: + + $ sudo docker inspect --format '{{ .NetworkSettings.IPAddress }}' some-postgres + $ sudo docker inspect --format '{{ .NetworkSettings.Ports }}' some-postgres + $ sudo docker run --rm --entrypoint=cat jodogne/orthanc-plugins /etc/orthanc/orthanc.json > /tmp/orthanc.json + +.. highlight:: json + +Add the following section to ``/tmp/orthanc.json`` (adapting the +values Host and Port to what docker inspect said above):: + + "PostgreSQL" : { + "EnableIndex" : true, + "EnableStorage" : true, + "Host" : "172.17.0.38", + "Port" : 5432, + "Database" : "orthanc", + "Username" : "postgres", + "Password" : "pgpassword" + } + +.. highlight:: bash + +Finally, you can start Orthanc:: + + $ sudo docker run -p 4242:4242 -p 8042:8042 --rm -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro jodogne/orthanc-plugins + + +Debugging +--------- + +For debugging purpose, you can start an interactive bash session as +follows:: + + $ sudo docker run -i -t --rm --entrypoint=bash jodogne/orthanc + $ sudo docker run -i -t --rm --entrypoint=bash jodogne/orthanc-plugins