Mercurial > hg > orthanc-book
changeset 393:43c5a1274740
doc for osimis/orthanc images
| author | Alain Mazy <alain@mazy.be> |
|---|---|
| date | Tue, 21 Apr 2020 15:23:50 +0200 |
| parents | 4bc6bcd83ae5 |
| children | ea7428e3761a |
| files | Sphinx/source/users/docker-osimis.rst Sphinx/source/users/docker.rst |
| diffstat | 2 files changed, 289 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Sphinx/source/users/docker-osimis.rst Tue Apr 21 15:23:50 2020 +0200 @@ -0,0 +1,286 @@ +.. _docker-osimis: +.. highlight:: bash + + +Osimis Orthanc Docker images +============================ + +.. contents:: + :depth: 3 + + +.. warning:: this is a preliminary documentation for images that are not publicly available yet + +Introduction +------------ + +Our commercial partner `Osimis <https://www.osimis.io>`__ +`publishes separated Docker images +<https://hub.docker.com/repository/docker/osimis/orthanc>`__ +that are used by their technical team in order to provide professional +support to their customers. + +These images have been designed to be used with ``docker-compose`` and +provide a configuration system through: + +- environment variables +- Docker secrets +- classical configuration files +- a mix of these options + +This `repository <https://bitbucket.org/osimis/orthanc-setup-samples/src>`__ +contains lots of examples on how to use these images. In particular, +`this example <https://bitbucket.org/osimis/orthanc-setup-samples/src/new-images/docker/all-usages/docker-compose.yml>`__ +shows all the way that can be used to generate the same +configuration in Orthanc. + +Note that these images have been re-written in April 2020. The documentation +for older images is still available `here <https://osimis.atlassian.net/wiki/spaces/OKB/pages/26738689/How+to+use+osimis+orthanc+Docker+images#Howtouseosimis/orthancDockerimages>`__ + +Environmnent variables +---------------------- + +Any part of the Orthanc configuration file can be configured through an +environment variable. Now that Orthanc and its plugins have hundreds of +configuration parameter, listing all these environment variable would be +too long. That's why we have defined a standard way of naming the variable: + ++---------------------------+----------------------------------------------+----------------------------------------------------------------+ +| Orthanc configuration | Environment variable | Sample value | ++===========================+==============================================+================================================================+ +| StableAge | ORTHANC__STABLE_AGE | ``30`` | ++---------------------------+----------------------------------------------+----------------------------------------------------------------+ +| DicomWeb.Root | ORTHANC__DICOM_WEB__ROOT | ``/dicom-web/`` | ++---------------------------+----------------------------------------------+----------------------------------------------------------------+ +| DicomWeb.Servers | ORTHANC__DICOM_WEB__SERVERS | ``{"sample": [ "http://127.0.0.1/dicom-web/"]}`` | ++---------------------------+----------------------------------------------+----------------------------------------------------------------+ + +To find out a environment variable name from an Orthanc configuration +(i.e. ``DicomWeb.StudiesMetadata`` is the ``path`` to a setting): + +- everytime a word contains a capital letter, insert an underscore ``_`` in front. + ``DicomWeb.StudiesMetadata`` now becomes ``Dicom_Web.Studies_Metadata`` +- everytime you go down one level in the json configuration, insert + a double underscore ``__``. ``Dicom_Web.Studies_Metadata`` now becomes + ``Dicom_Web__Studies_Metadata`` +- capitalize all letters. ``Dicom_Web__Studies_Metadata`` now becomes + ``DICOM_WEB__STUDIES_METADATA`` +- add ``ORTHANC__`` in front. ``DICOM_WEB__STUDIES_METADATA`` now becomes + ``ORTHANC__DICOM_WEB__STUDIES_METADATA`` + + +Special environment variables +----------------------------- + +Other environment variables are not related to the Orthanc configuration file +but can be specified to control the way Orthanc is run. + +- ``VERBOSE_STARTUP=true`` will allow you to debug the startup process and see + the configuration that has been provided to Orthanc. This setup should be + disabled in production since it might display secret information like passwords + in your logs +- ``VERBOSE_ENABLED=true`` will start Orthanc with the ``--verbose`` option +- ``TRACE_ENABLED=true`` will start Orthanc with the ``--trace`` option +- ``NO_JOBS=true`` will start Orthanc with the ``--no-jobs`` option +- ``UNLOCK=true`` will start Orthanc with the ``--unlock`` option +- ``MALLOC_ARENA_MAX=10`` will :ref:`control memory usage <scalability-memory>` + + +Configuration files +------------------- + +.. highlight:: yaml + +Configuration files should be stored in the ``/etc/orthanc/`` folder inside the Docker image. +This is done by building an image thanks to a ``Dockerfile``:: + + FROM osimis/orthanc + COPY orthanc.json /etc/orthanc/ + + +Configuration files can also be passed as secrets as shown in this ``docker-compose.yml``:: + + version: "3.3" + services: + orthanc-file-in-secrets: + image: osimis/orthanc + depends_on: [index-db] + ports: ["8201:8042"] + environment: + VERBOSE_STARTUP: "true" + + secrets: + - orthanc.secret.json + + secrets: + orthanc.secret.json: + file: orthanc.secret.json + +Finaly, a whole configuration file can be passed as a JSON through the ``ORTHANC_JSON`` environment variable:: + + version: "3.3" + services: + orthanc-file-in-env-var: + image: osimis/orthanc + depends_on: [index-db] + ports: ["8200:8042"] + environment: + VERBOSE_ENABLED: "true" + OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true" + + ORTHANC_JSON: | + { + "Name": "orthanc-file-in-env-var", + "PostgreSQL" : { + "Host": "index-db", + "Password": "pg-password" + }, + "RegisteredUsers": { + "demo": "demo" + } + } + + +Docker secrets +-------------- + +.. highlight:: yaml + +When using your container in a ``Docker Swarm`` or ``Kubernetes`` environment, +it is usually to pass sensitive information through ``Docker Secrets``. +For this purpose, any secret whose name is similar to the name of an +environment variable is considered as an environment variable:: + + version: "3.3" + services: + orthanc-with-direct-secret: + image: osimis/orthanc + depends_on: [index-db] + ports: ["8003:8042"] + environment: + ORTHANC__NAME: "orthanc-with-direct-secret" + VERBOSE_ENABLED: "true" + + OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED: "true" + + ORTHANC__POSTGRESQL__HOST: "index-db" + ORTHANC__REGISTERED_USERS: | + {"demo": "demo"} + + secrets: + - ORTHANC__POSTGRESQL__PASSWORD + secrets: + ORTHANC__POSTGRESQL__PASSWORD: + file: ORTHANC__POSTGRESQL__PASSWORD + + +Mixing configuration +-------------------- + +Parts of your configuration can be defined in a configuration file, +another part in an environment variable and yet another in a secret. +If the same setting is defined in multiple location, the latest one +will overwrite the first. Settings are evaluated in this order: + +- JSON files from ``/etc/orthanc/`` +- JSON files from ``/run/secrets`` (Docker secrets are copied there + by Docker) +- environment variables +- secret environment variables + +At this point, if some settings have not been defined yet, some defaults +are applied (see below). + + +Default configuration +--------------------- + +.. highlight:: json + +Orthanc and each plugin might have some default settings that might +eventually be different from the defaults included in the Orthanc +executable or the plugin library. + +.. below json is copied from orthanc-builder/docker/orthanc/orthanc-defaults.json + +Orthanc non-standard defaults:: + + { + "StorageDirectory" : "/var/lib/orthanc/db", + + "RemoteAccessAllowed": true, + "AuthenticationEnabled": true, + + "HttpsCACertificates" : "/etc/ssl/certs/ca-certificates.crt", + + "Plugins" : ["/usr/share/orthanc/plugins/"] + } + + +Plugins +------- + +Plugins are automatically enabled as soon as you define a setting +in their JSON section or as soon as you define to ``true`` their +specific environment variable. + +Below is a list of all plugins, their environment variable and their default configuration: + + +.. below table is obtained by running orthanc-builder/docker/orthanc/generatePluginDoc.py + + ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| Plugin | Environment variable | Default configuration | ++==================================================+==================================================+====================================================================================================+ +| **Authorization** | ``AUTHORIZATION_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **ConnectivityChecks** | ``CONNECTIVITY_CHECKS_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **DicomWeb** | ``DICOM_WEB_PLUGIN_ENABLED`` | .. code-block:: json | +| | | | +| | | { | +| | | "DicomWeb": { | +| | | "Enable": true | +| | | } | +| | | } | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **GoogleCloudPlatform** | ``GOOGLE_CLOUD_PLATFORM_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **OrthancWebViewer** | ``ORTHANC_WEB_VIEWER_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **OsimisWebViewerBasic** | ``OSIMIS_WEB_VIEWER1_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **OsimisWebViewerBasicAlpha** | ``OSIMIS_WEB_VIEWER1_ALPHA_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **PostgreSQL** | ``POSTGRESQL_PLUGIN_ENABLED`` | .. code-block:: json | +| | | | +| | | { | +| | | "PostgreSQL": { | +| | | "EnableIndex": true, | +| | | "EnableStorage": false, | +| | | "Port": 5432, | +| | | "Host": "HOST MUST BE DEFINED", | +| | | "Database": "postgres", | +| | | "Username": "postgres", | +| | | "Password": "postgres", | +| | | "EnableSsl": false, | +| | | "Lock": false | +| | | } | +| | | } | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **ServeFolders** | ``SERVE_FOLDERS_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **Transfers** | ``TRANSFERS_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **Worklists** | ``WORKLISTS_PLUGIN_ENABLED`` | .. code-block:: json | +| | | | +| | | { | +| | | "Worklists": { | +| | | "Enable": true, | +| | | "Database": "/var/lib/orthanc/worklists" | +| | | } | +| | | } | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ +| **Wsi** | ``WSI_PLUGIN_ENABLED`` | | ++--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+ \ No newline at end of file
--- a/Sphinx/source/users/docker.rst Tue Apr 21 08:58:56 2020 +0200 +++ b/Sphinx/source/users/docker.rst Tue Apr 21 15:23:50 2020 +0200 @@ -28,7 +28,7 @@ * Our commercial partner `Osimis <https://www.osimis.io>`__ also `publishes separated Docker images - <https://osimis.atlassian.net/wiki/spaces/OKB/pages/26738689/How+to+use+osimis+orthanc+Docker+images>`__. + <https://hub.docker.com/repository/docker/osimis/orthanc>`__. These ``osimis/orthanc`` images are used by the technical team of Osimis in order to provide professional support to their customers, with a configuration system that can be tuned through environment @@ -37,7 +37,8 @@ but they also include the :ref:`plugins edited by Osimis <plugins-osimis>`, notably the Osimis Web viewer (that is much more advanced than the Orthanc Web viewer) and the advanced authorization - plugin. + plugin. A :ref:`specific page <docker-osimis>` is availble to describe + how these images should be used. **Note for CentOS users:** The Docker environment might be difficult to configure on your platform. Hints are available on the `Orthanc Users