Mercurial > hg > orthanc-book
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 |
| 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 |
|
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 | 75 script of the Orthanc distribution. This process can also be used to |
| 76 restore the content of an Orthanc server after a corruption of its | |
| 77 database. | |
| 78 | |
| 79 For instance, the following command would recursively explore the | |
| 80 content of the ``OrthancStorage`` folder (where Orthanc stores its | |
| 81 DICOM files by default), and send each DICOM file inside this folder | |
| 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 | 84 |
| 85 $ python ImportDicomFiles.py 192.168.0.2 8042 OrthancStorage | |
| 86 | |
| 87 This method will only succeed if: | |
| 88 | |
| 161 | 89 * The source Orthanc uses the default storage area on the filesystem |
| 162 | 90 (i.e. the source Orthanc does *not* store its DICOM files using one |
| 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 | 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 | 95 OK for the source of Orthanc to use any of the "index plugins"), |
| 0 | 96 * You have command-line access to the source Orthanc, and |
| 97 * The transparent :ref:`compression` of the DICOM instances is | |
| 98 disabled (cf. option ``StorageCompression`` in the | |
| 99 :ref:`configuration file <configuration>`). | |
| 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 | 103 if the ``ImportDicomFiles.py`` script ends by saying that only half of |
| 104 the DICOM files were properly sent. This is because the JSON summaries | |
| 105 are not DICOM files, and are thus rejected by the target Orthanc | |
| 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 | 110 Generic replication |
| 111 ------------------- | |
| 112 | |
| 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 | 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. |