Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/postgresql.rst @ 31:93bbfaf0e62c
worklist instructions migrated to a specific page, indexing of Osimis Web viewer
| author | Sebastien Jodogne <s.jodogne@gmail.com> |
|---|---|
| date | Wed, 20 Jul 2016 11:35:54 +0200 |
| parents | 79b6d3ea92aa |
| children | 4eea0dc5f071 |
| rev | line source |
|---|---|
| 24 | 1 .. _postgresql: |
| 2 | |
| 3 | |
| 4 PostgreSQL plugins | |
| 5 ================== | |
| 6 | |
| 27 | 7 .. contents:: |
| 8 | |
| 9 The Orthanc project provides two **official** plugins to replace the | |
| 10 default storage area (on the filesystem) and the default SQLite index | |
| 11 by a PostgreSQL database. | |
| 12 | |
| 13 For general information, check out the `official homepage of the | |
| 14 plugins <http://www.orthanc-server.com/static.php?page=postgresql>`__. | |
| 15 | |
| 16 | |
| 17 | |
| 18 Compilation | |
| 19 ----------- | |
| 20 | |
| 21 .. highlight:: text | |
| 22 | |
| 23 The procedure to compile these plugins is similar of that for the | |
| 24 :ref:`core of Orthanc <compiling>`. The following commands should work | |
| 25 for every UNIX-like distribution (including GNU/Linux):: | |
| 26 | |
| 27 $ mkdir Build | |
| 28 $ cd Build | |
| 29 $ cmake .. -DSTATIC_BUILD=ON | |
| 30 $ make | |
| 31 | |
| 32 The compilation will produce 2 shared libraries, each containing one plugin for Orthanc: | |
| 33 | |
| 34 * ``OrthancPostgreSQLIndex`` replaces the default SQLite index of Orthanc by PostgreSQL. | |
| 35 * ``OrthancPostgreSQLStorage`` makes Orthanc store the DICOM files it receives into PostgreSQL. | |
| 36 | |
| 28 | 37 Pre-compiled binaries for Microsoft Windows `are also available |
| 27 | 38 <http://www.orthanc-server.com/browse.php?path=/plugin-postgresql>`__. |
| 30 | 39 A package for `Apple's Mac OS X |
| 27 | 40 <http://localhost/~jodogne/orthanc/static.php?page=download-mac>`__ |
| 41 are available courtesy of `Osimis <http://osimis.io/>`__. | |
| 42 | |
| 43 | |
| 44 Usage | |
| 45 ----- | |
| 46 | |
| 47 .. highlight:: json | |
| 48 | |
|
31
93bbfaf0e62c
worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
30
diff
changeset
|
49 You of course first have to :ref:`install Orthanc <binaries>`, with a |
| 28 | 50 version above 0.9.1. You then have to **create a database** dedicated |
| 51 to Orthanc on some PostgreSQL server. Please refer to the `PostgreSQL | |
| 52 documentation | |
| 27 | 53 <https://www.postgresql.org/docs/current/static/tutorial-createdb.html>`__. |
| 54 | |
| 55 Once Orthanc is installed and the database is created, you must add a | |
| 56 section in the :ref:`configuration file <configuration>` that | |
| 57 specifies the address of the **PostgreSQL server together with your | |
| 58 credentials**. You also have to tell Orthanc in which path it can find | |
| 59 the plugins: This is done by properly modifying the ``Plugins`` | |
| 60 option. You could for instance adapt the following configuration | |
| 61 file:: | |
| 62 | |
| 63 { | |
| 64 "Name" : "MyOrthanc", | |
| 65 [...] | |
| 66 "PostgreSQL" : { | |
| 67 "EnableIndex" : true, | |
| 68 "EnableStorage" : true, | |
| 69 "Host" : "localhost", | |
| 70 "Port" : 5432, | |
| 71 "Database" : "orthanc", | |
| 72 "Username" : "orthanc", | |
| 73 "Password" : "orthanc" | |
| 74 }, | |
| 75 "Plugins" : [ | |
| 76 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so", | |
| 77 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so" | |
| 78 ] | |
| 79 } | |
| 80 | |
| 81 Note that ``EnableIndex`` and ``EnableStorage`` must be explicitly set | |
| 82 to true, otherwise Orthanc will continue to use its default SQLite | |
| 83 back-end. | |
| 84 | |
| 85 .. highlight:: text | |
| 86 | |
| 87 Orthanc must of course be **restarted** after the modification of its | |
| 88 configuration file. The log will contain an output similar to:: | |
| 89 | |
| 90 $ ./Orthanc Configuration.json | |
| 91 W0212 16:30:34.576972 11285 main.cpp:632] Orthanc version: 0.8.6 | |
| 92 W0212 16:30:34.577386 11285 OrthancInitialization.cpp:80] Using the configuration from: Configuration.json | |
| 93 [...] | |
| 94 W0212 16:30:34.598053 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so | |
| 95 W0212 16:30:34.598470 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-index' (version 1.0) | |
| 96 W0212 16:30:34.598491 11285 PluginsManager.cpp:148] Using PostgreSQL index | |
| 97 W0212 16:30:34.608289 11285 main.cpp:379] Registering a plugin from: /home/jodogne/Subversion/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so | |
| 98 W0212 16:30:34.608916 11285 PluginsManager.cpp:258] Registering plugin 'postgresql-storage' (version 1.0) | |
| 99 W0212 16:30:34.608947 11285 PluginsManager.cpp:148] Using PostgreSQL storage area | |
| 100 [...] | |
| 101 W0212 16:30:34.674648 11285 main.cpp:530] Orthanc has started | |
| 102 | |
| 103 | |
| 104 .. highlight:: json | |
| 105 | |
| 106 Instead of specifying explicit authentication parameters, you can also | |
| 107 use the `PostgreSQL connection URIs syntax | |
| 108 <https://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING>`__. For | |
| 109 instance:: | |
| 110 | |
| 111 { | |
| 112 "Name" : "MyOrthanc", | |
| 113 [...] | |
| 114 "PostgreSQL" : { | |
| 115 "EnableIndex" : true, | |
| 116 "EnableStorage" : true, | |
| 117 "ConnectionUri" : "postgresql://username:password@localhost:5432/database" | |
| 118 }, | |
| 119 "Plugins" : [ | |
| 120 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so", | |
| 121 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so" | |
| 122 ] | |
| 123 } | |
| 124 | |
| 125 | |
| 126 **Remark:** The Debian Med project maintains `another useful set of | |
| 127 instructions | |
| 128 <https://anonscm.debian.org/viewvc/debian-med/trunk/packages/orthanc-postgresql/trunk/debian/README.Debian?view=markup>`__. | |
| 129 | |
| 130 | |
| 131 Advanced options | |
| 132 ---------------- | |
| 133 | |
| 134 Several advanced options are available as well to fine-tune the | |
| 135 configuration of the PostgreSQL plugins. They are documented below. | |
| 136 | |
| 137 | |
| 138 Locking | |
| 139 ^^^^^^^ | |
| 140 | |
| 141 .. highlight:: json | |
| 142 | |
| 143 By default, the plugins lock the database (using `PostgreSQL advisory | |
| 144 locks | |
| 145 <https://www.postgresql.org/docs/current/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS>`__) | |
| 146 to prevent other instances of Orthanc from using the same PostgreSQL | |
| 147 database. If you want several instances of Orthanc to share the same | |
| 148 database, set the ``Lock`` option to ``false`` in the configuration | |
| 149 file:: | |
| 150 | |
| 151 { | |
| 152 "Name" : "MyOrthanc", | |
| 153 [...] | |
| 154 "PostgreSQL" : { | |
| 155 "EnableIndex" : true, | |
| 156 "EnableStorage" : true, | |
| 157 "Lock" : false, | |
| 158 "ConnectionUri" : "postgresql://username:password@localhost:5432/database" | |
| 159 }, | |
| 160 "Plugins" : [ | |
| 161 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLIndex.so", | |
| 162 "/home/user/OrthancPostgreSQL/Build/libOrthancPostgreSQLStorage.so" | |
| 163 ] | |
| 164 } | |
| 165 | |
| 166 Obviously, one must be very cautious when sharing the same database | |
| 167 between instances of Orthanc. In particular, all these instances | |
| 168 should share the same configuration. | |
| 169 | |
| 170 | |
| 171 Keep-alive | |
| 172 ^^^^^^^^^^ | |
| 173 | |
| 174 .. highlight:: text | |
| 175 | |
| 176 After some period of inactivity (users have reported 10 hours), you | |
| 177 might `experience an error | |
| 178 <https://bitbucket.org/sjodogne/orthanc/issues/15/postgresql-exceptions-after-time>`__ | |
| 179 such as:: | |
| 180 | |
| 181 E0220 03:20:51.562601 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: server closed the connection unexpectedly. | |
| 182 This probably means the server terminated abnormally before or while processing the request. | |
| 183 E0220 06:51:03.924868 PluginsManager.cpp:163] Exception in database back-end: Error in PostgreSQL: no connection to the server | |
| 184 | |
| 185 This is due to a timeout in the PostgreSQL server. Please make sure to | |
| 186 `enable keep-alive | |
| 187 <http://dba.stackexchange.com/questions/97534/is-there-a-timeout-option-for-remote-access-to-postgresql-database>`__ | |
| 188 in the configuration of your PostgreSQL server |