Mercurial > hg > orthanc-book
changeset 1147:5875ab184744
merge?
| author | Benoit Crickboom <bc@orthanc.team> |
|---|---|
| date | Fri, 04 Apr 2025 15:14:35 +0200 |
| parents | 529cea35b08f (current diff) be06d0ab4bee (diff) |
| children | d7682d029efc |
| files | |
| diffstat | 6 files changed, 139 insertions(+), 48 deletions(-) [+] |
line wrap: on
line diff
--- a/Sphinx/source/faq/log.rst Fri Apr 04 15:12:32 2025 +0200 +++ b/Sphinx/source/faq/log.rst Fri Apr 04 15:14:35 2025 +0200 @@ -189,7 +189,8 @@ * Provided that you have left the ``DeidentifyLogs`` configuration to its ``true`` default value, Orthanc logs will not contain any sensitive - patient information. + patient information at ``default`` or ``verbose`` level; however, + at ``trace`` level, the DICOM logs will still contain PHI. * Starting from Orthanc 1.12.2, Orthanc is logging the thread name in the logs. If you need to revert back to the previous format, add the
--- a/Sphinx/source/faq/orthanc-storage.rst Fri Apr 04 15:12:32 2025 +0200 +++ b/Sphinx/source/faq/orthanc-storage.rst Fri Apr 04 15:14:35 2025 +0200 @@ -3,19 +3,41 @@ How does Orthanc store its database? ==================================== +Orthanc actually uses 2 different places to store its data: + +* the files are saved in the :ref:`Storage Area <orthanc-storage-area>`, + usually, a standard file-system but it can also be replaced by a cloud + :ref:`object storage <object-storage>` like AWS S3, Azure blob storage or Google cloud. +* a summary of all resources is saved in the :ref:`Index <orthanc-index>` + that is a SQL database. + +Orthanc always needs both the ``Storage`` and the ``Index`` and these 2 components +must always remain synchronized. + + .. _orthanc-storage-area: Storage area ------------ -**By default** (i.e. if no database plugin such as :ref:`PostgreSQL -<postgresql>` or :ref:`MySQL <mysql>` is used), Orthanc stores all the +**By default**, Orthanc stores all the DICOM files it receives in a folder called ``OrthancStorage`` on the -filesystem. +filesystem (defined in the ``StorageDirectory`` configuration in the +:ref:`configuration file <configuration>`). + +The default storage can also be replaced by a plugin to store these +files in an :ref:`object storage <object-storage>` like AWS S3, Azure +blob storage or Google cloud. -More precisely, the ``OrthancStorage`` folder contains a set of +Alternatively, the file storage can also be implemented inside a +:ref:`PostgreSQL <postgresql>` or :ref:`MySQL <mysql>` Database but +this is actually quite uncommon. + +More precisely, the ``Storage`` contains a set of so-called **attachments**, that may correspond to either a DICOM file, -a JSON file, or any user-defined file. Internally, each attachment is +a JSON file, or any user-defined file. + +Internally, each attachment is automatically associated with an `universally unique identifier (UUID) <https://en.wikipedia.org/wiki/Universally_unique_identifier>`__. Orthanc can be configured to compress these files on-the-fly in order @@ -29,21 +51,41 @@ folder, and the two next characters give the second-level folder. -SQLite index ------------- + +.. _orthanc-index: + +Orthanc Index +------------- + +Orthanc also maintains a summary of all the DICOM resources in a SQL +database in the so called ``Index``. This ``Index`` is mandatory to +rapidly provide information when browsing and accessing the resources +either through the :ref:`REST API of Orthanc <rest>` or through the +:ref:`DICOM protocol <dicom-guide>`. -Inside the same ``OrthancStorage`` folder, Orthanc maintains a `SQLite -database <https://en.wikipedia.org/wiki/SQLite>`__ called ``index`` -that **indexes** all these attachments. The database records, for each -attachment, its compression method, and its MD5 hashes before and +**By default**, this index is implemented in a `SQLite +database <https://en.wikipedia.org/wiki/SQLite>`__ that is stored +in the same folder as the files (if you are using a file-system). +This folder is defined by the ``IndexDirectory`` in the :ref:`configuration +option <configuration>`) + +The default ``Index`` can also be replaced by a plugin to store the +index in a :ref:`PostgreSQL <postgresql>`, :ref:`MySQL <mysql>` or +:ref:`ODBC <odbc>` Database. + + +Index content +------------- + +The ``Index`` database **indexes** all the attachments stored in the ``Storage``. +The database records, for each attachment, its compression method, and its MD5 hashes before and after compression in order to detect disk corruption (cf. the ``StoreMD5ForAttachments`` :ref:`configuration option <configuration>`). One attachment must be associated with one :ref:`DICOM resource <model-world>` (patient, study, series, or instance). Incoming DICOM -files and associated JSON summary are associated with one -instance-level resource, but user-defined attachments can be +files are associated with one instance-level resource, but user-defined attachments can be associated with any kind of resource. Given one DICOM resource, all of its child attachments are identified @@ -55,9 +97,10 @@ information for each DICOM resource, notably the :ref:`metadata <metadata>`, the :ref:`history of changes <changes>`, and an associative map that stores the so-called "main" DICOM tags (to avoid -accessing the storage folder are when this is not needed). The SQLite -database schema is kept as simple as possible, and can be found in the -following two files of the source code of Orthanc: +accessing the storage folder are when this is not needed). + +The database schema is kept as simple as possible, e.g, for SQLite, +the schema can be found in the following two files of the source code of Orthanc: `PrepareDatabase.sql <https://orthanc.uclouvain.be/hg/orthanc/file/Orthanc-1.12.6/OrthancServer/Sources/Database/PrepareDatabase.sql>`__ and `InstallTrackAttachmentsSize.sql @@ -67,20 +110,22 @@ Direct access ------------- -Directly accessing the content of the ``OrthancStorage`` folder and -the content of the SQLite/MySQL/PostgreSQL database is strongly +Directly accessing the content of the ``Storage`` folder and +the content of the SQLite/MySQL/PostgreSQL ``Index`` database is strongly discouraged for several reasons: -* The internal organization outlined above is only true when no +* The ``Storage`` internal organization outlined above is only true when no database plugin is used (e.g. the :ref:`PostgreSQL <postgresql>` and :ref:`MySQL <mysql>` plugins can be configured to store the attachments inside a database). * Orthanc can be configured to compress the attachments before writing - them on the disk (cf. the ``StorageCompression`` option). -* By directly reading the content of ``OrthancStorage``, you bypass + them on the disk (cf. the ``StorageCompression`` option) making them + less easily readable by an external tool (check the ``OrthancRecoverCompressedFile`` + executable in the Orthanc distribution). +* By directly reading/writing the content of the ``Storage``, you bypass all the locking mechanisms used by Orthanc, which might result in data corruption. -* One SQLite database should be accessed by at most one process at any +* If you are using SQLite for the ``Index``, one SQLite database should be accessed by at most one process at any time to avoid any problem (e.g. with NFS filesystems), for reasons that are `explained in the SQLite FAQ <https://www.sqlite.org/faq.html#q5>`__. Orthanc will stop if it @@ -89,10 +134,10 @@ successive versions of Orthanc or of the database plugins. As a consequence, it is **HIGHLY recommended NOT to directly access** -the ``OrthancStorage`` folder and the SQLite/MySQL/PostgreSQL +the ``Storage`` and the SQLite/MySQL/PostgreSQL ``Index`` database. Use the :ref:`REST API <rest>` instead, which contains primitives to access the attachments (cf. the ``.../attachments/...`` -URIs). +URIs) and all other resources. The only exception to this rule is for **read-only access when Orthanc is stopped**, e.g. as a part of a :ref:`backup <backup>` or
--- a/Sphinx/source/plugins.rst Fri Apr 04 15:12:32 2025 +0200 +++ b/Sphinx/source/plugins.rst Fri Apr 04 15:14:35 2025 +0200 @@ -175,6 +175,13 @@ announcement on the `Orthanc Users forum <https://groups.google.com/g/orthanc-users/c/q3Tncx3b6os/m/iFLq85fKAgAJ>`__. +* Oskar Bożek maintains `orthanc-radiant + <https://github.com/boskar/orthanc-radiant/>`__ as an Orthanc plugin + written in Python for invoking ``radiant://`` URI scheme from + Orthanc Explorer. Check out the original announcement on the + `Orthanc Users forum + <https://discourse.orthanc-server.org/t/radiant-dicom-viewer-uri-integration-plugin/5589?u=jodogne>`__. + Rust plugins ^^^^^^^^^^^^
--- a/Sphinx/source/plugins/authorization.rst Fri Apr 04 15:12:32 2025 +0200 +++ b/Sphinx/source/plugins/authorization.rst Fri Apr 04 15:14:35 2025 +0200 @@ -58,7 +58,7 @@ "/home/user/OrthancAuthorization/Build/libOrthancAuthorization.so" ], "Authorization" : { - // .. all options are document below + // .. all options are documented below } }
--- a/Sphinx/source/plugins/postgresql.rst Fri Apr 04 15:12:32 2025 +0200 +++ b/Sphinx/source/plugins/postgresql.rst Fri Apr 04 15:14:35 2025 +0200 @@ -58,19 +58,21 @@ "Name" : "MyOrthanc", "PostgreSQL" : { "EnableIndex" : true, - "EnableStorage" : true, + "EnableStorage" : false, // You likely don't need to enable this option "Host" : "localhost", "Port" : 5432, "Database" : "orthanc", "Username" : "orthanc", "Password" : "orthanc", - "EnableSsl" : false, // New in release 3.0 - "MaximumConnectionRetries" : 10, // New in release 3.0 - "ConnectionRetryInterval" : 5, // New in release 3.0 - "IndexConnectionsCount" : 50, // New in release 4.0 - new default value in 7.0 - "TransactionMode": "ReadCommitted",// New in release 6.0 - new default value in 7.0 - "EnableVerboseLogs": false, // New in release 6.0 - "HousekeepingInterval": 1 // New in release 7.0 + "Lock" : true, + "EnableSsl" : false, // New in release 3.0 + "MaximumConnectionRetries" : 10, // New in release 3.0 + "ConnectionRetryInterval" : 5, // New in release 3.0 + "IndexConnectionsCount" : 50, // New in release 4.0 - new default value in 7.0 + "TransactionMode": "ReadCommitted", // New in release 6.0 - new default value in 7.0 + "EnableVerboseLogs": false, // New in release 6.0 + "HousekeepingInterval": 1, // New in release 7.0 + "AllowInconsistentChildCounts": false // New in release 7.2 }, "Plugins" : [ "/home/user/orthanc-databases/BuildPostgreSQL/libOrthancPostgreSQLIndex.so", @@ -193,7 +195,6 @@ <revisions>` to protect metadata and attachments from concurrent modifications. - .. _postgresql-lock: @@ -249,12 +250,6 @@ in the configuration of your PostgreSQL server -Scalability -^^^^^^^^^^^ - -When configuring your PostgreSQL plugin, ensure you've read the :ref:`scalability section -<scalability>` - Transaction modes (new in version 6.0) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -269,6 +264,33 @@ - ``ReadCommitted`` that allows multiple threads or Orthanc instances to write at the same time to the same Database. This is the default setting starting from release 7.0. +Optimizations +^^^^^^^^^^^^^ + +* ``AllowInconsistentChildCounts`` has been added in the release 7.2 to provide + some optimization when accessing e.g tags like ``NumberOfStudyRelatedInstances``. + If set to ``true``, childCount values of recently ingested resources will be + incorrect until the next execution of the DB housekeeping thread. + + +Other options +^^^^^^^^^^^^^ + +* ``EnableVerboseLogs`` has been added in the release 6.0 to log the + SQL queries that are being executed. This is mainly target at developers. + +* ``HousekeepingInterval`` has been added in the release 7.0 to define the + interval (in seconds) at which the DB housekeeping thread is executed. The + DB housekeeping thread is in charge of updating values like the statistics + and childCount entries to speed up their computation. + + +Scalability +^^^^^^^^^^^ + +When configuring your PostgreSQL plugin, ensure you've read the :ref:`scalability section +<scalability>` + Upgrades/Downgrades ^^^^^^^^^^^^^^^^^^^ @@ -284,15 +306,23 @@ +---------------------------+-------------------------------------------+ | 6.0 - 6.2 | 2 | +---------------------------+-------------------------------------------+ -| from 7.0 | 3 | +| 7.0 - 7.1 | 3 | ++---------------------------+-------------------------------------------+ +| from 7.2 | 4 | +---------------------------+-------------------------------------------+ + Upgrades from one revision to the other is always automatic. Furthermore, if you are upgrading -from e.g plugin 3.3 to 7.0, Orthanc will apply all migration steps autonomously. +from e.g plugin 3.3 to 7.2, Orthanc will apply all migration steps autonomously. However, if, for some reasons, you would like to reinstall a previous plugin version, the older plugin might refuse to start because the revision is newer and unknown to it. +To downgrade from revision 4 to revision 3, one might run this procedure:: + + $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Downgrades/Rev4ToRev3.sql + $ psql -U postgres -f Rev4ToRev3.sql + To downgrade from revision 3 to revision 2, one might run this procedure:: $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Downgrades/Rev3ToRev2.sql @@ -336,6 +366,13 @@ $ psql -U postgres -f Rev2ToRev3.sql $ psql -U postgres -f PrepareIndex.sql +To upgrade manually from revision 3 to revision 4:: + + $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/Upgrades/Rev3ToRev4.sql + $ wget https://orthanc.uclouvain.be/hg/orthanc-databases/raw-file/default/PostgreSQL/Plugins/SQL/PrepareIndex.sql + $ psql -U postgres -f Rev3ToRev4.sql + $ psql -U postgres -f PrepareIndex.sql + These procedures are identical to the one performed automatically by Orthanc when it detects that an upgraded is required.
--- a/Sphinx/source/users/cookbook.rst Fri Apr 04 15:12:32 2025 +0200 +++ b/Sphinx/source/users/cookbook.rst Fri Apr 04 15:14:35 2025 +0200 @@ -36,11 +36,12 @@ Furthermore, if you are running Debian 9 (stretch), Debian 10 (buster), Debian 11 (bullseye), Debian 12 (bookworm), Ubuntu 18.04 LTS -(bionic), Ubuntu 20.04 LTS (focal), or Ubuntu 22.04 LTS (jammy) on an -**AMD64 architecture**, Sébastien Jodogne maintains a **standalone -Debian repository** that provides the latest versions of the LSB -binaries. For instance, here is how to install the :ref:`Stone Web -viewer <stone_webviewer>` on a barebone Docker setup:: +(bionic), Ubuntu 20.04 LTS (focal), Ubuntu 22.04 LTS (jammy), or +Ubuntu 24.04 LTS (noble) on an **AMD64 architecture**, Sébastien +Jodogne maintains a **standalone Debian repository** that provides the +latest versions of the LSB binaries. For instance, here is how to +install the :ref:`Stone Web viewer <stone_webviewer>` on a barebone +Docker setup:: # docker run --rm -t -i -p 8042:8042 -p 4242:4242 debian:9