Upgrade on Docker

Остановка и удаление контейнеров с предыдущей версией

$ docker stop ldap db arc
ldap
db
arc

$ docker rm -v ldap db arc
ldap
db
arc

или с использованием Docker Composite

$ docker-compose -p dcm4chee-arc down
Stopping dcm4cheearc_arc_1  ... done
Stopping dcm4cheearc_db_1   ... done
Stopping dcm4cheearc_ldap_1 ... done
Removing dcm4cheearc_arc_1  ... done
Removing dcm4cheearc_db_1   ... done
Removing dcm4cheearc_ldap_1 ... done
Removing network dcm4cheearc_default

Необязательно: удаление предыдущей конфигурации и развёртывания Wildfly

Необязательно удалить или переименовать каталог, который был примонтирован к /opt/wildfly/standalone, например:

$ sudo mv /var/local/dcm4chee-arc/wildfly /tmp

Начиная с 5.26.1 docker-контейнер архива перезаписывает предыдущие развёртывания и конфигурационные файлы при первом запуске. Ручное удаление конфигурационных файлов может по-прежнему потребоваться, если временная метка новых конфигурационных файлов в новом docker-образе старше, чем у примонтированного предыдущего конфигурационного файла.

Обновление схемы и данных конфигурации LDAP

Резервное копирование данных конфигурации LDAP (требуется для обновления с версий 2.4.44-Y.Y)

Экспортируйте конфигурацию, запущенную в предыдущей версии:

$ mkdir /tmp/backup
$ docker run --name prev-ldap --rm -d \
   -e LDAP_ROOTPASS=secret \
   -e LDAP_CONFIGPASS=secret \
   -v /var/local/dcm4chee-arc/ldap:/var/lib/openldap/openldap-data \ # Примечание 1
   -v /var/local/dcm4chee-arc/slapd.d:/etc/openldap/slapd.d \
   dcm4che/slapd-dcm4chee:2.6.7-33.1
$ docker exec prev-ldap export-data > /tmp/backup/data.ldif
$ docker exec prev-ldap export-users > /tmp/backup/users.ldif
$ docker exec prev-ldap export-realm-management > /tmp/backup/realm-management.ldif # Примечание 2
$ docker exec prev-ldap export-account > /tmp/backup/account.ldif
$ docker stop prev-ldap

Примечание 1: При экспорте из версий 2.4.44-Y.Y необходимо монтировать другие каталоги: -v /var/local/dcm4chee-arc/ldap:/var/lib/ldap \ -v /var/local/dcm4chee-arc/slapd.d:/etc/ldap/slapd.d \ dcm4che/slapd-dcm4chee:2.4.44-19.0
Примечание 2: Из-за опечатки при экспорте из версий 2.4.44-Y.Y необходимо вызывать $ docker exec prev-ldap export-realm-managment > /tmp/backup/realm-management.ldif

Восстановление данных конфигурации LDAP из резервной копии (требуется для обновления с версий 2.4.44-Y.Y)

Очистите каталоги хоста, содержащие базу данных LDAP и конфигурацию сервера OpenLDAP предыдущей версии. Например:

$ sudo rm -r /var/local/dcm4chee-arc/ldap
$ sudo rm -r /var/local/dcm4chee-arc/slapd.d

Запустите новую версию, пропустив начальную конфигурацию и передав экспортированную конфигурацию для начального импорта. (Обратите внимание на изменённый путь к каталогам данных и конфигурации внутри контейнера между версиями 2.4.44-Y.Y и 2.4.50-Y.Y!)

$ docker run --rm \
   -e LDAP_ROOTPASS=secret \
   -e LDAP_CONFIGPASS=secret \
   -e SKIP_INIT_CONFIG=true \
   -e IMPORT_LDIF="/backup/data.ldif /backup/users.ldif /backup/realm-management.ldif /backup/account.ldif" \
   -v /tmp/backup:/backup \
   -v /var/local/dcm4chee-arc/ldap:/var/lib/openldap/openldap-data \
   -v /var/local/dcm4chee-arc/slapd.d:/etc/openldap/slapd.d \
   dcm4che/slapd-dcm4chee:2.6.10-34.3
66f1909b.00a06d65 0x7a04e861eb28 @(#) $OpenLDAP: slapd 2.6.8 (Sep 25 2024 06:46:47) $
    openldap
66f1909b.01f40f80 0x7a04e861eb28 slapd starting
adding new entry "cn=dicom,cn=schema,cn=config"
adding new entry "cn=dcm4che,cn=schema,cn=config"
adding new entry "cn=dcm4chee-archive,cn=schema,cn=config"
:
adding new entry "cn=manage-consent,ou=account,dc=dcm4che,dc=org"
adding new entry "cn=view-applications,ou=account,dc=dcm4che,dc=org"

Остановите контейнер сочетанием CTRL+C.

Запуск новой версии сервера OpenLDAP

Запустите новую версию сервера OpenLDAP, примонтировав те же каталоги хоста, а также задайте те же переменные окружения, что использовались при запуске предыдущей версии. Например:

$ docker run --network=dcm4chee_default --name ldap \
           -p 389:389 \
           -e ARCHIVE_DEVICE_NAME=<archive-device-name> \
           -e ARCHIVE_AET=<archive-aet> \
           -e ARCHIVE_HOST=<archive-host> \
           -v /var/local/dcm4chee-arc/ldap:/var/lib/openldap/openldap-data \
           -v /var/local/dcm4chee-arc/slapd.d:/etc/openldap/slapd.d \
           -d dcm4che/slapd-dcm4chee:2.6.10-34.3

Если используется Docker Compose, скорректируйте теги версий образов в docker-compose.yaml соответствующим образом, перед запуском сервера OpenLDAP и сервера PostgreSQL выполнив

$ docker-compose -p dcm4chee-arc up -d ldap
Creating network "dcm4cheearc_default" with the default driver
Creating dcm4cheearc_ldap_1 ... done

Обновление схемы LDAP (не требуется, если данные конфигурации LDAP были восстановлены из резервной копии)

$ docker exec slapd-container-name update-schema
modifying entry "cn={4}dicom,cn=schema,cn=config"
modifying entry "cn={5}dcm4che,cn=schema,cn=config"
modifying entry "cn={6}dcm4chee-archive,cn=schema,cn=config"
modifying entry "cn={7}dcm4chee-archive-ui,cn=schema,cn=config"

Обновление конфигурации LDAP

Если вы не вносили структурные изменения в предоставленную конфигурацию по умолчанию — например, не добавляли/удаляли Network Application Entities или не настраивали несколько Archive Devices — то применения предоставленных скриптов обновления должно быть достаточно. Для обновления с версии более старой, чем самая последняя из предыдущих, например с 5.34.0 до 5.34.2, примените скрипты обновления для предыдущих версий, например:

$ docker exec slapd-container-name update-data 5.34.1
$ docker exec slapd-container-name update-data 5.34.2

после чего можно обновить конфигурацию LDAP до текущей версии:

$ docker exec slapd-container-name update-data 5.34.3
adding entry "cn=dicom-tls,dicomDeviceName=dcm4chee-arc,cn=Devices,cn=DICOM Configuration,dc=dcm4che,dc=org"
:

Если вы добавили дополнительные Network Application Entities к Archive Device, необходимо дополнительно применить

$ docker exec -e ARCHIVE_AET=<additional-archive-aet> slapd-container-name update-comp DCM4CHEE 5.34.1
$ docker exec -e ARCHIVE_AET=<additional-archive-aet> slapd-container-name update-comp DCM4CHEE 5.34.2
$ docker exec -e ARCHIVE_AET=<additional-archive-aet> slapd-container-name update-comp DCM4CHEE 5.34.3

для каждого добавленного Network Application Entity архивного устройства (Archive Device).

Если вы добавили дополнительные Archive Devices, необходимо дополнительно применить

$ docker exec -e ARCHIVE_DEVICE_NAME=<additional-archive-device-name> \
              -e ARCHIVE_AET=<aet-of-additional-archive> \
              -e ARCHIVE_HOST=<host-of-additional-archive> \
              -e AE_TITLE_IOCM_REGULAR_USE=<iocm-regular-use-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_QUALITY=<iocm-quality-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_PAT_SAFETY=<iocm-pat-safety-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_WRONG_MWL=<iocm-wrong-mwl-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_EXPIRED=<iocm-expired-aet-of-additional-archive> \
              -e AE_TITLE_AS_RECEIVED=<as-received-aet-of-additional-archive> \
              -e AE_TITLE_WORKLIST=<worklist-aet-of-additional-archive> \
              slapd-container-name update-data 5.34.3
$ docker exec -e ARCHIVE_DEVICE_NAME=<additional-archive-device-name> \
              -e ARCHIVE_AET=<aet-of-additional-archive> \
              -e ARCHIVE_HOST=<host-of-additional-archive> \
              -e AE_TITLE_IOCM_REGULAR_USE=<iocm-regular-use-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_QUALITY=<iocm-quality-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_PAT_SAFETY=<iocm-pat-safety-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_WRONG_MWL=<iocm-wrong-mwl-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_EXPIRED=<iocm-expired-aet-of-additional-archive> \
              -e AE_TITLE_AS_RECEIVED=<as-received-aet-of-additional-archive> \
              -e AE_TITLE_WORKLIST=<worklist-aet-of-additional-archive> \
              slapd-container-name update-data 5.34.3
$ docker exec -e ARCHIVE_DEVICE_NAME=<additional-archive-device-name> \
              -e ARCHIVE_AET=<aet-of-additional-archive> \
              -e ARCHIVE_HOST=<host-of-additional-archive> \
              -e AE_TITLE_IOCM_REGULAR_USE=<iocm-regular-use-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_QUALITY=<iocm-quality-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_PAT_SAFETY=<iocm-pat-safety-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_WRONG_MWL=<iocm-wrong-mwl-aet-of-additional-archive> \
              -e AE_TITLE_IOCM_EXPIRED=<iocm-expired-aet-of-additional-archive> \
              -e AE_TITLE_AS_RECEIVED=<as-received-aet-of-additional-archive> \
              -e AE_TITLE_WORKLIST=<worklist-aet-of-additional-archive> \
              slapd-container-name update-data 5.34.3

для каждого добавленного Archive Device.

А если вы добавили дополнительные Network Application Entities к дополнительному Archive Device, необходимо дополнительно применить

$ docker exec -e ARCHIVE_DEVICE_NAME=<additional-archive-device-name> \
              -e ARCHIVE_AET=<additional-aet-of-additional-archive> \
              slapd-container-name update-comp DCM4CHEE 5.34.3
$ docker exec -e ARCHIVE_DEVICE_NAME=<additional-archive-device-name> \
              -e ARCHIVE_AET=<additional-aet-of-additional-archive> \
              slapd-container-name update-comp DCM4CHEE 5.34.3
$ docker exec -e ARCHIVE_DEVICE_NAME=<additional-archive-device-name> \
              -e ARCHIVE_AET=<additional-aet-of-additional-archive> \
              slapd-container-name update-comp DCM4CHEE 5.34.3

для каждого добавленного Network Application Entity дополнительного Archive Device.

Начиная с v5.6.0 имена пользователей и пароли для защищённой версии хранятся в LDAP. Для обновления с версий, предшествующих v5.6.0, можно импортировать учётные данные пользователя/пароля по умолчанию user/user и admin/admin, выполнив

$ docker exec slapd-container-name init-users
modifying entry "olcDatabase={1}hdb,cn=config"
adding new entry "ou=users,dc=dcm4che,dc=org"
adding new entry "uid=admin,ou=users,dc=dcm4che,dc=org"
adding new entry "uid=user,ou=users,dc=dcm4che,dc=org"
adding new entry "cn=admin,ou=users,dc=dcm4che,dc=org"
adding new entry "cn=user,ou=users,dc=dcm4che,dc=org"

Начиная с v5.8.0 разрешения управления realm предоставляются пользователю admin. Для обновления с версий, предшествующих v5.8.0, можно предоставить эти разрешения, выполнив

$ docker exec slapd-container-name init-realm-management
adding new entry "ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=create-client,ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=impersonation,ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=manage-authorization,ou=realm-management,dc=dcm4che,dc=org"
:

Начиная с v5.9.0 роль auditlog назначается пользователю admin. Для обновления с версий, предшествующих v5.9.0, можно назначить эту роль, выполнив

$ docker exec slapd-container-name init-auditlog-group
adding new entry "cn=auditlog,ou=users,dc=dcm4che,dc=org"

В v5.10.2 изменена конфигурация того, какая Storage System используется конкретным Archive AE: атрибут LDAP, ссылающийся на Storage ID для объектного хранилища, используемого AE, изменён с dcmStorageID на dcmObjectStorageID, и больше нельзя настроить Storage ID по умолчанию для объектного хранилища на уровне Device. Соответствующие строки в update-config-5.10.2.ldif:

dn: dicomDeviceName=dcm4chee-arc,cn=Devices,cn=DICOM Configuration,dc=dcm4che,dc=org
changetype: modify
delete: dcmStorageID
-

dn: dicomAETitle=DCM4CHEE,dicomDeviceName=dcm4chee-arc,cn=Devices,cn=DICOM Configuration,dc=dcm4che,dc=org
changetype: modify
add: dcmObjectStorageID
dcmObjectStorageID: fs1
-

Если вы изменили Storage ID по умолчанию fs1, можно либо скорректировать update-config-5.10.2.ldif перед его применением, либо применить изменение повторно после этого — либо непосредственно в LDAP, либо через UI.

До v5.10.4 любое изменение конфигурации архива через UI препятствует дальнейшей отправке Audit-сообщений из-за вставки универсального Audit Suppress Criteria в существующие Audit Loggers архивного устройства (Archive Device). Вы можете удалить этот Audit Suppress Criteria из Audit Logger(ов) - через UI в v5.10.4+, либо - удалить дочерний узел Audit Logger непосредственно в LDAP, выполнив console $ docker exec slapd-container-name fix#783 deleting entry "cn=cn,cn=Audit Logger,dicomDeviceName=dcm4chee-arc,cn=Devices,cn=DICOM Configuration,dc=dcm4che,dc=org"

В v5.10.5 Keycloak обновлён до 3.2.1.Final, чья Realm Adminstration Console предоставляет дополнительные операции. При обновлении с версии, предшествующей v5.10.5, предоставьте дополнительные разрешения управления realm для этих операций пользователю admin, выполнив

$ docker exec slapd-container-name add-query-permissions
adding new entry "cn=query-users,ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=query-groups,ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=query-realms,ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=query-clients,ou=realm-management,dc=dcm4che,dc=org"

Начиная с v5.13.0 разрешения пользователей настраиваемы. Для обновления с версий, предшествующих v5.13.0, можно инициировать разрешения по умолчанию, выполнив

$ docker exec slapd-container-name init-ui-config

Начиная с v5.15.0 TLS можно включить, добавив ldaps:// в переменную окружения Docker LDAP_URLS. Для обновления с версий, предшествующих v5.15.0, необходимо инициализировать конфигурацию TLS, выполнив

$ docker exec slapd-container-name update-tls
modifying entry "cn=config"

прежде чем вы сможете включить TLS через переменную окружения LDAP_URLS.

Начиная с Keycloak 12.0.0.Final, управление account предоставляется отдельным клиентским приложением Keycloak, которое требует назначения пользователям определённых клиентских ролей account, чтобы позволить им просматривать/изменять/удалять собственную учётную информацию. Вызов

$ docker exec slapd-container-name init-account admin user
adding new entry "ou=account,dc=dcm4che,dc=org"
adding new entry "cn=view-profile,ou=account,dc=dcm4che,dc=org"
adding new entry "cn=delete-account,ou=account,dc=dcm4che,dc=org"
adding new entry "manage-account,ou=account,dc=dcm4che,dc=org"
adding new entry "manage-consent,ou=account,dc=dcm4che,dc=org"

при этом вы можете скорректировать admin и user, если вы изменяли имена пользователей по сравнению с исходной настройкой.

В v5.25.0 значение по умолчанию пользовательской роли SUPER_USER_ROLE изменено с admin на root, и помимо предыдущих пользователей по умолчанию user и admin, по умолчанию создаётся третий пользователь root, связанный с SUPER_USER_ROLE. Поскольку пользователь admin связан с ADMIN_USER_ROLE (по умолчанию: admin), а не с SUPER_USER_ROLE, преднастроенные пользовательские разрешения для ADMIN_USER_ROLE фактически применяются.

При обновлении с версии, предшествующей v5.25.0, можно создать такого пользователя root, выполнив

$ docker exec slapd-container-name add-root-user <user-name> <password>

и можно сбросить преднастроенные пользовательские разрешения, выполнив

$ docker exec slapd-container-name del-ui-config
$ docker exec slapd-container-name init-ui-config

В v5.31.2 пользовательская роль, необходимая для аутентификации через OIDC, была отделена от пользовательских ролей, связанных с разрешениями, что повлекло изменение назначенных ролей преднастроенных пользователей:

Имя	Пароль	Роль(и)
`root`	`changeit`	`auth` `root` `auditlog` `ADMINISTRATOR` все роли, заданные клиентом `realm-management`
`admin`	`changeit`	`auth` `admin`
`user`	`changeit`	`auth` `user`

При обновлении с версии, предшествующей v5.31.2, можно создать такую роль auth и назначить её всем пользователям, выполнив

$ docker exec slapd-container-name init-role auth root
$ docker exec slapd-container-name assign-role-to-user auth user
$ docker exec slapd-container-name assign-role-to-user auth admin

и снять предыдущую роль user со всех пользователей — кроме обычного пользователя user — выполнив

$ docker exec slapd-container-name unassign-role-to-user auth root
$ docker exec slapd-container-name unassign-role-to-user auth admin

Обновление старшей версии PostgreSQL

Не требуется при обновлении с версии PostgreSQL с такой же старшей версией, например с 15.6-32 до 15.9-33. см. PostgreSQL Documentation, Upgrading a PostgreSQL Cluster

Запуск новой версии сервера PostgreSQL

Запустите новую версию сервера PostgreSQL, примонтировав те же каталоги хоста, что и в предыдущей версии, например:

$ docker run --network=dcm4chee_default --name db \
           -p 5432:5432 \
           -e POSTGRES_DB=pacsdb \
           -e POSTGRES_USER=pacs \
           -e POSTGRES_PASSWORD=pacs \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           -v /var/local/dcm4chee-arc/db:/var/lib/postgresql/data \
           -d dcm4che/postgres-dcm4chee:17.4-34

Если используется Docker Compose, скорректируйте теги версий образов в docker-compose.yaml соответствующим образом, перед запуском сервера PostgreSQL выполнив

$ docker-compose -p dcm4chee-arc up -d db
Creating network "dcm4cheearc_default" with the default driver
Creating dcm4cheearc_db_1   ... done

Обновление PostgreSQL

Как правило, не требуется при обновлении с версии, отличающейся только третьим компонентом номера версии (например, с 5.34.2 до 5.34.3). Единственное исключение — обновление с 5.31.0 до 5.31.1, для которого необходимо создать недостающий индекс, выполнив

$ docker exec postgres-container-name update-schema 5.31.1

что можно применять уже на запущенной предыдущей версии архива.

Опционально создайте резервную копию базы данных в текстовый файл, выполнив

$ docker exec postgres-container-name dump > db_backup.sql

Для обновления с версии более старой, чем самая последняя из предыдущих, например с 5.31.x до 5.34.x, необходимо применить скрипты обновления для предыдущих версий, например:

$ docker exec postgres-container-name update-schema 5.32
$ docker exec postgres-container-name update-schema 5.33

после чего можно обновить PostgreSQL до текущей версии:

$ docker exec postgres-container-name update-schema 5.34
ALTER TABLE
:

Можно сократить время простоя архива на время обновления БД, разделив обновление схемы БД на 3 этапа:

Первый:

$ docker exec postgres-container-name update-schema 5.34-1

может быть применён уже на запущенной предыдущей версии архива.

Необходимо остановить архив перед применением второго этапа:

$ docker exec postgres-container-name update-schema 5.34-2

Можно запустить новую версию архива уже до применения третьего этапа:

$ docker exec postgres-container-name update-schema 5.34-3

Пока вы не применили третий этап, можно откатиться к предыдущей версии архива без отмены обновления схемы БД, выполненного на первом и втором этапах.

Запуск новой версии DCM4CHEE Archive 5

Начиная с v5.10.5, Keycloak удалён из Docker-образов архива и теперь предоставляется отдельным Docker-образом #916. Поэтому теперь его нужно запускать отдельно от архива, как описано в Run secured archive services on a single host.

Начиная с v5.10.5, Audit Record Repository Proxy удалён из Docker-образа архива, а Keycloak Gatekeeper предоставляется как замена в виде отдельного Docker-образа. Поэтому теперь его нужно запускать отдельно от архива, как описано в Run-secured-archive-services-and-Elastic-Stack-on-a-single-host.

Начиная с v5.16.1, Wildfly Administration Console защищённой версии архива также защищён Keycloak #1890. Поэтому необходимо зарегистрировать WildFly Administration Console как OIDC-клиента в Keycloak, как описано в Run secured archive services on a single host, и назначить роль ADMINSTRATOR пользователям, которые должны иметь доступ к Wildfly Administration Console.

Начиная с v5.17.0, отправка системных журналов в Logstash настраивается через переменные окружения. Больше нет отдельных Docker-образов Keycloak и архива (с тегом: VERSION-logstash) для этого.

Запустите новую версию DCM4CHEE Archive 5, примонтировав те же каталоги хоста, что и в предыдущей версии, например:

$ docker run --network=dcm4chee_default --name arc \
           -p 8080:8080 \
           -p 8443:8443 \
           -p 9990:9990 \
           -p 9993:9993 \
           -p 11112:11112 \
           -p 2762:2762 \
           -p 2575:2575 \
           -p 12575:12575 \
           -e POSTGRES_DB=pacsdb \
           -e POSTGRES_USER=pacs \
           -e POSTGRES_PASSWORD=pacs \
           -e WILDFLY_WAIT_FOR="ldap:389 db:5432" \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           -v /var/local/dcm4chee-arc/wildfly:/opt/wildfly/standalone \
           -d dcm4che/dcm4chee-arc-psql:5.34.3

или с использованием Docker Composite:

$ docker-compose -p dcm4chee-arc up -d arc
dcm4cheearc_ldap_1 is up-to-date
dcm4cheearc_db_1 is up-to-date
Creating dcm4cheearc_arc_1  ... done

(Необязательно) очистка docker-образов предыдущей версии

$ docker rmi dcm4che/slapd-dcm4chee:2.6.7-33.1 dcm4che/dcm4chee-arc-psql:5.33.1 dcm4che/postgres-dcm4chee:17.1-33
Untagged: dcm4che/slapd-dcm4chee:2.6.7-33.1
Deleted: sha256:56ad388eb143cf986bef47012aa47803bdb1106969d7d7bc6dcb19febc3246a3
Untagged: dcm4che/dcm4chee-arc-psql:5.34.0
Deleted: sha256:82f84ec39508d8f5a78576b66ad5c134b84e717c784eb75c9f36bb7e029c0bf7
Untagged: dcm4che/postgres-dcm4chee:17.1-33
Deleted: sha256:a9529f4cced095873e7dc8b2d2702ed2ff5664a22d22a86fc00f8e4b82e2c146