Mercurial > hg > orthanc-book

annotate Sphinx/source/plugins/serve-folders.rst @ 991:1316bc62b5d5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
migration to UCLouvain servers
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 21 Nov 2023 21:09:02 +0100
parents 2922fb1bd65e
children 683f238333cf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. _serve-folders:
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
31
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
4 Sample Serve Folders plugin
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
5 ===========================
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 This **official** plugin enables Orthanc to serve additional folders
31
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
8 from the filesystem using its embedded Web server. This plugin is
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
9 extremely useful when creating new Web applications on the top of the
34
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 31
diff changeset
10 REST API of Orthanc, as it allows to fulfill the :ref:`same-origin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 31
diff changeset
11 policy <same-origin>` without setting up a reverse proxy.
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
12
31
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
13 The source code of this sample plugin is `available in the source
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
14 distribution of Orthanc
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
15 <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancServer/Plugins/Samples/ServeFolders/>`__
63
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
16 (GPLv3+ license).
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
17
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
18
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
19 Basic usage
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
20 -----------
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
21
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
22 1. First, generate the :ref:`default configuration of Orthanc <configuration>`.
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
23 2. Then, modify the ``Plugins`` option to point to the folder containing
64
a3df3c2b68cf import the documentation of the Worklists sample plugin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 63
diff changeset
24 the shared library of the plugin.
63
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
25 3. Finally, create a section ``ServeFolders`` in the configuration file to
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
26 specify which folder you want to serve, and at which URI.
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
27
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
28 .. highlight:: json
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
29
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
30 For instance, the following excerpt would load the plugins from the
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
31 working directory, then would map the content of the folder
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
32 ``/home/jodogne/WWW/fosdem`` as URI "http://localhost:8042/fosdem"::
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
33
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
34 {
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
35 [...]
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
36 "Plugins" : [
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
37 "."
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
38 ],
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
39 "ServeFolders" : {
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
40 "/fosdem" : "/home/jodogne/WWW/fosdem"
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
41 }
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
42 }
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
43
65
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
44
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
45 Advanced usage
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
46 --------------
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
47
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
48 Starting with Orthanc 1.2.0, the Serve Folders plugin features some
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
49 more advanced configuration options, besides simply the list of
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
50 folders to be served:
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
51
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
52 * The **MIME types** associated with the file extensions can be
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
53 configured through the ``Extensions`` option. By default, the most
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
54 common file extensions for Web applications such as ``.html``,
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
55 ``.js`` and ``.css`` are defined.
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
56 * The HTTP client can be asked to enable/disable its **caching
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
57 mechanism** with the ``AllowCache`` option. By default, this option
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
58 is set ``false`` (request no caching), as the most common use for
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
59 this plugin consists in supporting the development of Web
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
60 applications (with which caching would interfere). Note that this
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
61 option is only informative: The client might choose to ignore it.
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
62 * The plugin will automatically generate an `HTTP entity tag
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
63 <https://en.wikipedia.org/wiki/HTTP_ETag>`__ (**ETag**) for each
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
64 served resource, if the ``GenerateETag`` option is set to ``true``
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
65 (the default). The ETag is computed as the MD5 of the resource and
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
66 acts as a fingerprint.
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
67
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
68 If one of these advanced options is used, the list of served folders
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
69 must be moved to a ``Folders`` sub-option. Here is an example of such
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
70 an advanced configuration::
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
71
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
72 {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
73 [...]
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
74 "Plugins" : [
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
75 "."
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
76 ],
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
77 "ServeFolders" : {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
78 "AllowCache" : false,
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
79 "GenerateETag" : true,
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
80 "Extensions" : {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
81 ".mp4" : "video/mp4"
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
82 },
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
83 "Folders" : {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
84 "/fosdem" : "/home/jodogne/WWW"
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
85 }
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
86 }
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
87 }