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