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