Mercurial > hg > orthanc-book
view Sphinx/source/users/docker-osimis.rst @ 393:43c5a1274740
doc for osimis/orthanc images
| author | Alain Mazy <alain@mazy.be> |
|---|---|
| date | Tue, 21 Apr 2020 15:23:50 +0200 |
| parents | |
| children | d44f6f93a987 |
line wrap: on
line source
.. _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`` | | +--------------------------------------------------+--------------------------------------------------+----------------------------------------------------------------------------------------------------+