Mercurial > hg > orthanc-book

annotate Sphinx/source/plugins/serve-folders.rst @ 1113:a588960a72e5 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
spelling
author Alain Mazy <am@orthanc.team>
date Mon, 28 Oct 2024 09:23:08 +0100
parents 683f238333cf
children
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
1043
683f238333cf reorganized the list of plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
7 .. contents::
683f238333cf reorganized the list of plugins
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 991
diff changeset
8
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 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
10 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
11 extremely useful when creating new Web applications on the top of the
34
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 31
diff changeset
12 REST API of Orthanc, as it allows to fulfill the :ref:`same-origin
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 31
diff changeset
13 policy <same-origin>` without setting up a reverse proxy.
24
25fa874803ab plugins inside book
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
14
31
93bbfaf0e62c worklist instructions migrated to a specific page, indexing of Osimis Web viewer
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 24
diff changeset
15 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
16 distribution of Orthanc
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
17 <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
18 (GPLv3+ license).
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
19
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 Basic usage
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
22 -----------
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
23
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
24 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
25 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
26 the shared library of the plugin.
63
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
27 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
28 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
29
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
30 .. highlight:: json
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
31
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
32 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
33 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
34 ``/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
35
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
36 {
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 "Plugins" : [
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
39 "."
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
40 ],
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
41 "ServeFolders" : {
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
42 "/fosdem" : "/home/jodogne/WWW/fosdem"
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
43 }
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
44 }
34ccc7fc7ef3 migrate the doc of ServeFolder
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 34
diff changeset
45
65
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 Advanced usage
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
48 --------------
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
49
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
50 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
51 more advanced configuration options, besides simply the list of
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
52 folders to be served:
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
53
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
54 * 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
55 configured through the ``Extensions`` option. By default, the most
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
56 common file extensions for Web applications such as ``.html``,
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
57 ``.js`` and ``.css`` are defined.
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
58 * 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
59 mechanism** with the ``AllowCache`` option. By default, this option
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
60 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
61 this plugin consists in supporting the development of Web
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
62 applications (with which caching would interfere). Note that this
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
63 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
64 * The plugin will automatically generate an `HTTP entity tag
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
65 <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
66 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
67 (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
68 acts as a fingerprint.
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
69
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
70 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
71 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
72 an advanced configuration::
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 {
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 "Plugins" : [
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
77 "."
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
78 ],
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
79 "ServeFolders" : {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
80 "AllowCache" : false,
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
81 "GenerateETag" : true,
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
82 "Extensions" : {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
83 ".mp4" : "video/mp4"
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
84 },
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
85 "Folders" : {
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
86 "/fosdem" : "/home/jodogne/WWW"
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
87 }
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
88 }
731d6c12f599 advanced options of ServeFolders
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 64
diff changeset
89 }