annotate Sphinx/source/users/replication.rst @ 1113:a588960a72e5 default tip

spelling
author Alain Mazy <am@orthanc.team>
date Mon, 28 Oct 2024 09:23:08 +0100
parents 1316bc62b5d5
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
1 .. highlight:: bash
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
2 .. _replication:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
3
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
4 Replication and upgrade
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
5 =======================
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
6
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
7 This page explains how to replicate the content of one instance of
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
8 Orthanc to another instance of Orthanc. This is useful to **upgrade**
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
9 between :ref:`versions of the database schema <db-versioning>`, or to
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
10 create **mirrored DICOM servers**.
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
11
75
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
12
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
13 Upgrade the database schema
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
14 ---------------------------
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
15
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
16 As explained :ref:`elsewhere in the Orthanc Book <db-versioning>`,
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
17 successive versions of Orthanc might use a different version of the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
18 database schema. If this happens, Orthanc will refuse to start (with
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
19 an explicit message in its :ref:`logs <log>`), to let the user decides
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
20 whether she actually wants to upgrade the database.
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
21
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
22 At this point, the user could indeed choose to modify its
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
23 :ref:`configuration file <configuration>` in order to create a new
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
24 database elsewhere on the filesystem (if using the default SQLite
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
25 backend), or on the database management system (e.g. if using
154
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 76
diff changeset
26 :ref:`PostgreSQL <postgresql>` or :ref:`MySQL/MariaDB <mysql>`). This
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 76
diff changeset
27 is important to let the user experiment a new version of Orthanc,
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 76
diff changeset
28 while keeping the older version up and running.
75
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
29
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
30 If you decide to upgrade the database schema, you have to apply the
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
31 following 3 steps:
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
32
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
33 1. If not done yet, stop the running Orthanc service:
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
34
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
35 * Under Microsoft Windows, use the `services control panel
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
36 <https://en.wikipedia.org/wiki/Windows_service>`__.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
37 * Under Debian, use ``sudo /etc/init.d/orthanc stop``.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
38
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
39 2. Manually call Orthanc with the ``--upgrade`` command-line option,
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
40 and point to your configuration file:
75
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
41
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
42 * Under Microsoft Windows, ``Orthanc.exe c:/Orthanc/ --upgrade``.
75
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
43 * Under Debian, use ``sudo /usr/sbin/Orthanc /etc/orthanc/ --upgrade``.
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
44
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
45 3. Once the upgrade process is over, restart the Orthanc service:
75
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
46
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
47 * Under Microsoft Windows, use the `services control panel
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
48 <https://en.wikipedia.org/wiki/Windows_service>`__.
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
49 * Under Debian, use ``sudo /etc/init.d/orthanc start``.
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
50
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
51 **Important remarks:**
75
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 46
diff changeset
52
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
53 * Orthanc is now considered as **stable**, which means that no upgrade
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
54 in the database schema should occur in the near future.
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
55 * Depending on the size of the Orthanc database, upgrading the
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
56 database schema might take time, as this operation implies
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
57 re-reading all the DICOM instances from the disk.
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
58 * In the case of the official Debian and Fedora packages, the default
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
59 location of the database changes with the version of its schema.
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
60 For instance, DB schema version 6 will be stored in
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
61 ``/var/lib/orthanc/db-v6/``. If upgrading the package (and if the
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
62 configuration files are purged), a new database will automatically
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
63 be created on the disk. Old data can be recovered either by changing
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
64 the configuration in ``/etc/orthanc/`` to point to the previous
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
65 location of the database then using ``--upgrade`` as written above,
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
66 or by using the instructions for replication below.
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
67
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
68
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
69 Direct access to the filesystem
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
70 -------------------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
71
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
72 The most direct way to replicate an instance of Orthanc consists in
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
73 using the `ImportDicomFiles
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 959
diff changeset
74 <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancServer/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`_
959
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
75 script of the Orthanc distribution. This process can also be used to
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
76 restore the content of an Orthanc server after a corruption of its
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
77 database.
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
78
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
79 For instance, the following command would recursively explore the
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
80 content of the ``OrthancStorage`` folder (where Orthanc stores its
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
81 DICOM files by default), and send each DICOM file inside this folder
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
82 to the instance of Orthanc whose REST API is listening on
76
c2f2202f54f2 more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 75
diff changeset
83 ``http://192.168.0.2:8042``::
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
84
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
85 $ python ImportDicomFiles.py 192.168.0.2 8042 OrthancStorage
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
86
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
87 This method will only succeed if:
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
88
161
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
89 * The source Orthanc uses the default storage area on the filesystem
162
ce125a0a95e5 clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 161
diff changeset
90 (i.e. the source Orthanc does *not* store its DICOM files using one
ce125a0a95e5 clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 161
diff changeset
91 of the "storage area plugins", such as for `PostgreSQL
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 162
diff changeset
92 <https://www.orthanc-server.com/static.php?page=postgresql>`_ or
161
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 154
diff changeset
93 `MySQL/MariaDB
358
011b01ccf52d fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 162
diff changeset
94 <https://www.orthanc-server.com/static.php?page=mysql>`_ - but it's
162
ce125a0a95e5 clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 161
diff changeset
95 OK for the source of Orthanc to use any of the "index plugins"),
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
96 * You have command-line access to the source Orthanc, and
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
97 * The transparent :ref:`compression` of the DICOM instances is
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
98 disabled (cf. option ``StorageCompression`` in the
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
99 :ref:`configuration file <configuration>`).
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
100
46
12b204ee328d remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
101 **Important remark:** Because of :ref:`the way Orthanc stores its
12b204ee328d remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
102 database <orthanc-storage>` on the filesystem, it is *entirely normal*
959
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
103 if the ``ImportDicomFiles.py`` script ends by saying that only half of
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
104 the DICOM files were properly sent. This is because the JSON summaries
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
105 are not DICOM files, and are thus rejected by the target Orthanc
22a19433820b clarification
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 449
diff changeset
106 server. More information are available `on the discussion group
46
12b204ee328d remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
107 <https://groups.google.com/d/msg/orthanc-users/Zlhtcpo76qQ/tp8EqaRCAQAJ>`__.
12b204ee328d remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
108
12b204ee328d remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 0
diff changeset
109
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
110 Generic replication
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
111 -------------------
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
112
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
113 If you cannot use the first method, you can use the `Replicate
991
1316bc62b5d5 migration to UCLouvain servers
Sebastien Jodogne <s.jodogne@gmail.com>
parents: 959
diff changeset
114 <https://orthanc.uclouvain.be/hg/orthanc/file/default/OrthancServer/Resources/Samples/Python/Replicate.py>`_
0
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
115 script of the Orthanc distribution. This script will use the REST API
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
116 of both the source and target instances of Orthanc. For instance::
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
117
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
118 $ python Replicate.py http://orthanc:password@localhost:8042/ http://192.168.0.2/
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
119
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
120 Obviously, contrarily to the first method, the source instance of
901e8961f46e initial commit
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
diff changeset
121 Orthanc must be up and running during the replication.