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