Mercurial > hg > orthanc-book
annotate Sphinx/source/plugins/google-cloud-platform.rst @ 451:938206110483
added object storage
| author | Alain Mazy <alain@mazy.be> |
|---|---|
| date | Fri, 03 Jul 2020 12:52:11 +0200 |
| parents | 2922fb1bd65e |
| children | a4ed4e883337 |
| rev | line source |
|---|---|
| 254 | 1 .. _google: |
| 2 | |
| 3 | |
| 4 Google Cloud Platform plugin | |
| 5 ============================ | |
| 6 | |
| 7 .. contents:: | |
| 8 | |
| 255 | 9 |
| 10 Introduction | |
| 11 ------------ | |
| 12 | |
| 13 Osimis freely provides the `source code | |
| 449 | 14 <https://hg.orthanc-server.com/orthanc-gcp/file/default/>`__ of a plugin |
| 361 | 15 to interface Orthanc with the Healthcare API of `Google Cloud Platform |
| 259 | 16 (GCP) <https://en.wikipedia.org/wiki/Google_Cloud_Platform>`__ through |
| 17 `DICOMweb <https://www.dicomstandard.org/dicomweb/>`__. | |
| 255 | 18 |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
19 This GCP plugin turns Orthanc into a DICOMweb client connected to GCP |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
20 servers, enabling the upload of DICOM images using STOW-RS, the |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
21 querying of the cloud content using QIDO-RS, and the retrieval of |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
22 remote content using WADO-RS. These operations can be possibly |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
23 :ref:`scripted <dicomweb-client>` thanks to the REST API of Orthanc. |
| 255 | 24 |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
25 Concretely, the role of the GCP plugin is to `manage the credentials |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
26 <https://cloud.google.com/docs/authentication/>`__ to Google Cloud |
| 255 | 27 Platform. It requires the official :ref:`DICOMweb plugin <dicomweb>` |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
28 to be installed, as all the user interactions are done through the |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
29 latter plugin. As soon as Orthanc is started, the GCP plugin |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
30 automatically acquires then periodically refreshes the access tokens, |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
31 transparently updating the remote :ref:`DICOMweb servers |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
32 <dicomweb-client-config>` that are known to the DICOMweb plugin. The |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
33 access tokens can be derived either from service accounts, or from |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
34 user accounts. |
| 255 | 35 |
| 36 This page makes the assumption that you have created a Google Cloud | |
| 37 Platform project, in which you have enabled the `Healthcare API | |
| 38 <https://cloud.google.com/healthcare/>`__, and in which you have | |
| 39 created a `DICOM store | |
| 40 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. | |
| 41 | |
| 42 | |
| 43 | |
| 44 Compilation | |
| 45 ----------- | |
| 46 | |
| 47 .. highlight:: text | |
| 48 | |
| 49 The procedure to compile the GCP plugin is similar of that for the | |
| 50 :ref:`core of Orthanc <compiling>`. The following commands should work | |
| 51 on any recent UNIX-like distribution (including GNU/Linux):: | |
| 52 | |
| 53 $ mkdir Build | |
| 54 $ cd Build | |
| 55 $ cmake .. -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release | |
| 56 $ make | |
| 57 | |
| 58 The compilation produces a shared library | |
| 259 | 59 ``OrthancGoogleCloudPlatform`` that contains the GCP |
| 451 | 60 plugin. |
| 255 | 61 |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
62 Under the hood, the GCP plugin is built on the top of the official |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
63 `Google Cloud Platform C++ Client Libraries |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
64 <https://github.com/googleapis/google-cloud-cpp>`__. |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
65 |
| 255 | 66 |
| 451 | 67 Given this plugin is used to interface with a commercial & proprietary |
| 68 service, pre-compiled Windows/Docker binaries are available only for | |
| 69 companies who have subscribed for a `support contract <https://www.osimis.io/en/services.html#cloud-plugins>`__ at Osimis. | |
| 70 | |
| 255 | 71 |
| 72 Configuration | |
| 73 ------------- | |
| 74 | |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
75 Dependencies |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
76 ^^^^^^^^^^^^ |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
77 |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
78 As explained above, the GCP plugin requires Orthanc (with version |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
79 above 1.5.4), and the :ref:`official DICOMweb plugin <dicomweb>` to be |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
80 installed (with version above 1.0). All the communications with Google |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
81 Cloud Platform are done using the DICOMweb plugin, and the |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
82 responsibility of the GCP plugin is to aquire and periodically refresh |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
83 the access tokens whose lifetime is limited. |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
84 |
| 255 | 85 |
| 86 Common parameters | |
| 87 ^^^^^^^^^^^^^^^^^ | |
| 88 | |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
89 There are some common parameters to be set. Firstly, the ``Plugins`` |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
90 :ref:`configuration option <configuration>` of Orthanc must contain |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
91 the path that contains the ``OrthancGoogleCloudPlatform`` shared |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
92 library. |
| 255 | 93 |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
94 Secondly, obtaining the access tokens for Google Cloud Platform |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
95 necessitates a sequence of HTTPS requests. As a consequence, the |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
96 Orthanc configuration must specify how the authenticity of the Google |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
97 servers is verified. You have two possibilities to that end: |
| 255 | 98 |
| 99 1. Disabling the verification of the remote servers (**not recommended | |
| 100 in production**). This is done by setting option ``HttpsVerifyPeers`` | |
| 101 to ``false``. | |
| 102 | |
| 103 2. Providing a list of `trusted Certificate Authorities (CA) | |
| 104 <https://curl.haxx.se/docs/sslcerts.html>`__ to the HTTPS client | |
| 105 that is internally used by Orthanc (namely, `cURL | |
| 106 <https://en.wikipedia.org/wiki/CURL>`__). This is done by properly | |
| 299 | 107 setting ``HttpsCACertificates`` option, so that it points to a file |
| 255 | 108 containing a store of CA certificates. Depending on your operating |
| 109 system, this file can be found as follows: | |
| 110 | |
| 111 * On Debian-based system, the standard file | |
| 112 ``/etc/ssl/certs/ca-certificates.crt`` can be used. | |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
113 * On other systems (including Microsoft Windows), the cURL project |
|
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
114 provides `CA certificates |
| 255 | 115 <https://curl.haxx.se/docs/caextract.html>`__ that are extracted |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
116 from Mozilla. |
| 255 | 117 |
| 259 | 118 Note that to debug HTTPS communications, you have the possibility of |
| 119 setting the ``HttpVerbose`` configuration option of Orthanc to | |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
120 ``true``. It can also be useful to run Orthanc in ``--verbose`` mode |
| 259 | 121 (check out :ref:`this page <log>`). |
| 255 | 122 |
| 254 | 123 |
| 124 | |
| 255 | 125 Service account |
| 126 ^^^^^^^^^^^^^^^ | |
| 127 | |
| 128 As explained on the `Google documentation | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
129 <https://cloud.google.com/docs/authentication>`__, *"a service account |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
130 is a Google account that represents an application, as opposed to |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
131 representing an end user"*. This is presumably the most common |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
132 situation in the case of Orthanc. |
| 255 | 133 |
| 134 You first have to `create a service account | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
135 <https://cloud.google.com/docs/authentication/getting-started>`__ for |
|
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
136 your application. This will produce a JSON file (say, |
| 255 | 137 ``dicom-osimis.json``) that you have to store securely on the server |
| 138 that will run Orthanc. | |
| 139 | |
| 140 .. highlight:: json | |
| 141 | |
| 142 Secondly, you have to modify the :ref:`Orthanc configuration | |
| 143 <configuration>` in order to provide the GCP plugin with your service | |
| 144 account file and with the parameters of your `DICOM store | |
| 145 <https://cloud.google.com/healthcare/docs/how-tos/dicom>`__. Here is a | |
| 256 | 146 sample, minimalist configuration of Orthanc:: |
| 255 | 147 |
| 148 { | |
| 149 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", | |
| 150 "Plugins" : [ "." ], | |
| 151 "GoogleCloudPlatform" : { | |
| 152 "Accounts": { | |
| 153 "my-google" : { | |
| 154 "Project" : "osimis-test", | |
| 155 "Location" : "europe-west2", | |
| 156 "Dataset" : "test", | |
| 157 "DicomStore" : "dicom", | |
| 158 "ServiceAccountFile" : "dicom-osimis.json" | |
| 159 } | |
| 160 } | |
| 161 } | |
| 162 } | |
| 163 | |
| 164 | |
| 165 In this example, once the GCP plugin has succeeded to authenticate | |
| 166 using the service account, the DICOMweb plugin will provide access to | |
| 167 the cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the | |
| 168 REST API of Orthanc. | |
| 169 | |
| 170 | |
| 171 User account | |
| 172 ^^^^^^^^^^^^ | |
| 173 | |
| 174 User account is an alternative to service account, and can be used | |
| 175 *"when the application needs to access resources on behalf of an end | |
| 176 user"* (check out the `Google documentation | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
299
diff
changeset
|
177 <https://cloud.google.com/docs/authentication/end-user>`__). |
| 255 | 178 |
| 179 .. highlight:: json | |
| 180 | |
| 181 The easiest way of setting up a user account is through the `gcloud | |
| 182 command-line tool <https://cloud.google.com/sdk/gcloud/>`__. | |
| 256 | 183 `Google's quick-starts |
| 255 | 184 <https://cloud.google.com/sdk/docs/quickstarts>`__ explain how to |
| 185 initialize the environment depending on your operating system (check | |
| 186 out the "Initialize the SDK" sections, which essentially boil down to | |
| 187 calling ``gcloud init``). | |
| 188 | |
| 189 | |
| 190 .. highlight:: bash | |
| 191 | |
| 192 Once the ``gcloud init`` command-line has been invoked, you can | |
| 259 | 193 extract credentials to be used by Orthanc by typing the following |
| 194 command:: | |
| 255 | 195 |
| 196 $ gcloud auth print-access-token --format json | |
| 197 | |
| 198 | |
| 199 .. highlight:: json | |
| 200 | |
|
260
f9e7036d81d0
updating DICOMweb documentation
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
259
diff
changeset
|
201 This command generates a JSON file containing all the required |
| 255 | 202 information, that can be written to a file (say, |
| 256 | 203 ``dicom-user.json``). Given this file, here is a sample, minimalist |
| 255 | 204 configuration of Orthanc:: |
| 205 | |
| 206 { | |
| 207 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", | |
| 208 "Plugins" : [ "." ], | |
| 209 "GoogleCloudPlatform" : { | |
| 210 "Accounts": { | |
| 211 "my-google" : { | |
| 212 "Project" : "osimis-test", | |
| 213 "Location" : "europe-west2", | |
| 214 "Dataset" : "test", | |
| 215 "DicomStore" : "dicom", | |
| 216 "AuthorizedUserFile" : "dicom-osimis.json" | |
| 217 } | |
| 218 } | |
| 219 } | |
| 220 } | |
| 221 | |
| 222 In this example, once the GCP plugin has succeeded to authenticate | |
| 223 using the user account, the DICOMweb plugin will provide access to the | |
| 224 cloud DICOM store at URI ``/dicom-web/servers/my-google/`` of the REST | |
| 225 API of Orthanc. | |
| 226 | |
| 227 | |
| 228 .. highlight:: bash | |
| 229 | |
| 230 Note that only 3 fields in the JSON file produced by the ``gcloud auth | |
| 259 | 231 print-access-token`` command are required: ``client_id``, |
| 232 ``client_secret``, and ``refresh_token``. Instead of using the full | |
| 233 JSON file, you can extract only these fields, e.g. using the `jq | |
| 255 | 234 <https://stedolan.github.io/jq/>`__ command-line tool:: |
| 235 | |
| 236 $ gcloud auth print-access-token --format json | jq '{ AuthorizedUserClientId: .client_id, AuthorizedUserClientSecret:.client_secret, AuthorizedUserRefreshToken:.refresh_token }' | |
| 237 { | |
| 238 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com", | |
| 239 "AuthorizedUserClientSecret": "ZmssLNXXXXXX", | |
| 240 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX" | |
| 241 } | |
| 242 | |
| 243 | |
| 244 .. highlight:: json | |
| 245 | |
| 259 | 246 These fields can then be copied/pasted as follows in order to create a |
| 247 configuration for Orthanc that is equivalent to the one using the | |
| 248 separate JSON file:: | |
| 255 | 249 |
| 250 { | |
| 251 "HttpsCACertificates": "/etc/ssl/certs/ca-certificates.crt", | |
| 252 "Plugins" : [ "." ], | |
| 253 "GoogleCloudPlatform" : { | |
| 254 "Accounts": { | |
| 255 "my-google" : { | |
| 256 "Project" : "osimis-test", | |
| 257 "Location" : "europe-west2", | |
| 258 "Dataset" : "test", | |
| 259 "DicomStore" : "dicom", | |
| 260 "AuthorizedUserClientId": "XXXXXXXXXX.apps.googleusercontent.com", | |
| 261 "AuthorizedUserClientSecret": "ZmssLNXXXXXX", | |
| 262 "AuthorizedUserRefreshToken": "1/e2ngXXXXXX" | |
| 263 } | |
| 264 } | |
| 265 } | |
| 266 } | |
| 259 | 267 |
| 268 | |
| 269 Advanced options | |
| 270 ^^^^^^^^^^^^^^^^ | |
| 271 | |
| 272 .. highlight:: json | |
| 273 | |
| 274 Some advanced configuration options are available as well, as | |
| 275 summarized in this excerpt:: | |
| 276 | |
| 277 { | |
| 278 ... | |
| 279 // In seconds, must be large enough to send/receive your largest studies | |
| 280 // using WADO or STOW, depending on the speed of your Internet connection | |
| 281 "HttpTimeout" : 600, | |
| 282 | |
| 283 "GoogleCloudPlatform" : { | |
| 284 ... | |
| 285 // Path to the URL of the GCP services | |
| 286 "BaseUrl" : "https://healthcare.googleapis.com/v1beta1/" | |
| 287 } | |
| 288 } |