Mercurial > hg > orthanc-book
annotate Sphinx/source/users/replication.rst @ 848:dd3f89d1ab0f
fix
| author | Alain Mazy <am@osimis.io> |
|---|---|
| date | Thu, 19 May 2022 09:06:24 +0200 |
| parents | 2922fb1bd65e |
| children | 22a19433820b |
| rev | line source |
|---|---|
| 0 | 1 .. highlight:: bash |
| 2 .. _replication: | |
| 3 | |
| 4 Replication and upgrade | |
| 5 ======================= | |
| 6 | |
| 7 This page explains how to replicate the content of one instance of | |
| 8 Orthanc to another instance of Orthanc. This is useful to **upgrade** | |
| 9 between :ref:`versions of the database schema <db-versioning>`, or to | |
| 10 create **mirrored DICOM servers**. | |
| 11 | |
| 75 | 12 |
| 13 Upgrade the database schema | |
| 14 --------------------------- | |
| 15 | |
| 16 As explained :ref:`elsewhere in the Orthanc Book <db-versioning>`, | |
| 17 successive versions of Orthanc might use a different version of the | |
| 18 database schema. If this happens, Orthanc will refuse to start (with | |
| 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 | 26 :ref:`PostgreSQL <postgresql>` or :ref:`MySQL/MariaDB <mysql>`). This |
| 27 is important to let the user experiment a new version of Orthanc, | |
| 28 while keeping the older version up and running. | |
| 75 | 29 |
| 30 If you decide to upgrade the database schema, you have to apply the | |
| 31 following 3 steps: | |
| 32 | |
| 33 1. If not done yet, stop the running Orthanc service: | |
| 34 | |
| 35 * Under Microsoft Windows, use the `services control panel | |
| 36 <https://en.wikipedia.org/wiki/Windows_service>`__. | |
| 37 * Under Debian, use ``sudo /etc/init.d/orthanc stop``. | |
| 38 | |
| 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 | 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 | 43 * Under Debian, use ``sudo /usr/sbin/Orthanc /etc/orthanc/ --upgrade``. |
| 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 | 46 |
| 47 * Under Microsoft Windows, use the `services control panel | |
| 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 | 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 | 67 |
| 68 | |
| 69 Direct access to the filesystem | |
| 70 ------------------------------- | |
| 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 |
| 449 | 74 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/ImportDicomFiles/ImportDicomFiles.py>`_ |
| 0 | 75 script of the Orthanc distribution. For instance, the following |
|
76
c2f2202f54f2
more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
76 command would recursively explore the content of the |
|
c2f2202f54f2
more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
77 ``OrthancStorage`` folder (where Orthanc stores its DICOM files by |
|
c2f2202f54f2
more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
78 default), and send each DICOM file inside this folder to the instance |
|
c2f2202f54f2
more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
79 of Orthanc whose REST API is listening on |
|
c2f2202f54f2
more information about upgrade
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
75
diff
changeset
|
80 ``http://192.168.0.2:8042``:: |
| 0 | 81 |
| 82 $ python ImportDicomFiles.py 192.168.0.2 8042 OrthancStorage | |
| 83 | |
| 84 This method will only succeed if: | |
| 85 | |
| 161 | 86 * The source Orthanc uses the default storage area on the filesystem |
| 162 | 87 (i.e. the source Orthanc does *not* store its DICOM files using one |
| 88 of the "storage area plugins", such as for `PostgreSQL | |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
162
diff
changeset
|
89 <https://www.orthanc-server.com/static.php?page=postgresql>`_ or |
| 161 | 90 `MySQL/MariaDB |
|
358
011b01ccf52d
fixing external hyperlinks
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
162
diff
changeset
|
91 <https://www.orthanc-server.com/static.php?page=mysql>`_ - but it's |
| 162 | 92 OK for the source of Orthanc to use any of the "index plugins"), |
| 0 | 93 * You have command-line access to the source Orthanc, and |
| 94 * The transparent :ref:`compression` of the DICOM instances is | |
| 95 disabled (cf. option ``StorageCompression`` in the | |
| 96 :ref:`configuration file <configuration>`). | |
| 97 | |
|
46
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
98 **Important remark:** Because of :ref:`the way Orthanc stores its |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
99 database <orthanc-storage>` on the filesystem, it is *entirely normal* |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
100 that the ``ImportDicomFiles.py`` script ends by saying that only half |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
101 of the DICOM files were properly sent. This is because the JSON |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
102 summaries are not DICOM files, and are thus rejected by the target |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
103 Orthanc server. More information are available `on the discussion |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
104 group |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
105 <https://groups.google.com/d/msg/orthanc-users/Zlhtcpo76qQ/tp8EqaRCAQAJ>`__. |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
106 |
|
12b204ee328d
remark about replication
Sebastien Jodogne <s.jodogne@gmail.com>
parents:
0
diff
changeset
|
107 |
| 162 | 108 |
| 109 | |
| 0 | 110 Generic replication |
| 111 ------------------- | |
| 112 | |
| 113 If you cannot use the first method, you can use the `Replicate | |
| 449 | 114 <https://hg.orthanc-server.com/orthanc/file/default/OrthancServer/Resources/Samples/Python/Replicate.py>`_ |
| 0 | 115 script of the Orthanc distribution. This script will use the REST API |
| 116 of both the source and target instances of Orthanc. For instance:: | |
| 117 | |
| 118 $ python Replicate.py http://orthanc:password@localhost:8042/ http://192.168.0.2/ | |
| 119 | |
| 120 Obviously, contrarily to the first method, the source instance of | |
| 121 Orthanc must be up and running during the replication. |