Upgrade on Docker - dcm4che/dcm4chee-arc-light GitHub Wiki

$ docker stop ldap db arc
ldap
db
arc

$ docker rm -v ldap db arc
ldap
db
arc

or using 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

Optionally remove or rename the directory, which was mapped to /opt/wildfly/standalone, e.g.:

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

Since 5.26.1, the archive docker container will overwrite previous deployments and configuration files on first startup. Manually deletion of configuration files may be still necessary, if the timestamp of the new configuration files provided in the new docker image is older than the mapped out previous configuration file.

Export the configuration running the previous version:

$ 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 \ # Note 1
   -v /var/local/dcm4chee-arc/slapd.d:/etc/openldap/slapd.d \
   dcm4che/slapd-dcm4chee:2.6.7-33.0
$ 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 # Note 2
$ docker exec prev-ldap export-account > /tmp/backup/account.ldif
$ docker stop prev-ldap

• Note 1: You have to mount different directories on exporting from 2.4.44-Y.Y versions:

     -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
  

• Note 2: Caused by a typo, you have to invoke

  $ docker exec prev-ldap export-realm-managment > /tmp/backup/realm-management.ldif
  

  on exporting from 2.4.44-Y.Y versions!

Purge the host directories containing the LDAP database and the OpenLDAP server configuration of previous version. E.g.:

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

Run the new version with skipping the initial configuration and passing the export configuration for initial import. (Be aware of the changed path of the data and configuration directory inside of the container between 2.4.44-Y.Y and 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.7-33.0
66f1909b.00a06d65 0x7a04e861eb28 @(#) $OpenLDAP: slapd 2.6.7 (Feb  1 2024 19:18: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"

Stop the container by CTRL+C.

Run new version of OpenLDAP Server, mounting the same host directories and also set the same Envirionment Variables as used running the previous version. E.g.:

$ 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.7-33.0

If using Docker Compose adjust the version tags of the images in docker-compose.yaml accordingly, before starting the OpenLDAP Server and PostgreSQL Server by

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

$ 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"

If one did not make structural changes to the provided default configuration - e.g. by adding/removing Network Application Entities or by configuring multiple Archive Devices - then applying the provided update scripts should be sufficient. To update from an older version than the most-recent previous version, e.g. from 5.31.1 to 5.33.0, apply the update scripts for the previous versions, e.g.:

$ docker exec slapd-container-name update-data 5.31.2
$ docker exec slapd-container-name update-data 5.32.0

before one can update the LDAP configuration to the current version by:

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

If you have added additional Network Application Entities to the Archive Device, you have to additionally apply

$ docker exec -e ARCHIVE_AET=<additional-archive-aet> slapd-container-name update-comp DCM4CHEE 5.31.2
$ docker exec -e ARCHIVE_AET=<additional-archive-aet> slapd-container-name update-comp DCM4CHEE 5.32.0
$ docker exec -e ARCHIVE_AET=<additional-archive-aet> slapd-container-name update-comp DCM4CHEE 5.33.0

for each added Network Application Entity of the Archive Device.

If you have added additional Archive Devices, you have to additionally apply

$ 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.33.0
$ 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.33.0
$ 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.33.0

for each added Archive Device.

And if you have added additional Network Application Entities to the additional Archive Device, you have to additionally apply

$ 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.33.0
$ 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.33.0
$ 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.33.0

for each added Network Application Entity of the additional Archive Device.

Since v5.6.0, user names and passwords for the secured version are stored in LDAP. For upgrading from previous versions than v5.6.0 one may import default user/passwords user/user and admin/admin by

$ 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"

Since v5.8.0, realm management permissions are granted to the admin user. For upgrading from previous versions than v5.8.0 one may grant these permissions by

$ 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"
:

Since v5.9.0, role auditlog is assigned to the admin user. For upgrading from previous versions than v5.9.0 one may assign this role by

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

In v5.10.2, the configuration which Storage System is used by a particular Archive AE changed: The LDAP attribute which reference the Storage ID for object storage used by the AE changed from dcmStorageID to dcmObjectStorageID, and it's no longer possible to configure a default Storage ID used for object storage on Device level. The corresponding lines in update-config-5.10.2.ldif are

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
-

If one changed the default Storage ID fs1, one may either adjust update-config-5.10.2.ldif before applying it oneself, or apply one's change afterward again - either directly in LDAP or using the UI.

Before v5.10.4, any configuration change of the archive using the UI prevents further emission of Audit messages caused by the insert of an universal Audit Suppress Criteria to existing Audit Loggers of the Archive Device. You may either remove that Audit Suppress Criteria from the Audit Logger(s)

• using the UI in v5.10.4+, or
• remove the Audit Logger child node directly in LDAP by

  $ 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"

In v5.10.5, Keycloak was upgraded to 3.2.1.Final, which Realm Adminstration Console provides additional operations. When upgrading from before v5.10.5, grant additional realm management permissions for these operations to the admin user by

$ 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"

Since v5.13.0, user permissions are configurable. For upgrading from previous versions than v5.13.0 one may initiate default permissions by

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

Since v5.15.0, TLS can be enabled by including ldaps:// in Docker Environment Variable LDAP_URLS. For upgrading from previous versions than v5.15.0 you have to initialize the TLS configuration by

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

before you can enable TLS by ENV LDAP_URLS.

Starting with Keycloak 12.0.0.Final, Account management is provided by a particular Keycloak client application, which requires to assign particular account client roles to users to permit them to view/update/delete their own account information. Invoking

$ 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"

whereas you may adjust the admin and user, if you modified the user names from initial setup.

In v5.25.0, the default value of SUPER_USER_ROLE user role was changed from admin to root and beside previous default users user and admin a third user root associated SUPER_USER_ROLE is created by default. Because user admin is associated with ADMIN_USER_ROLE (default: admin), and no longer with the SUPER_USER_ROLE, the pre-configured user permissions for ADMIN_USER_ROLE get actually applied.

When upgrading from before v5.25.0, you may create such root user by

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

and you may reset pre-configured user permissions by

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

In v5.31.2, the user role required for authentification by OIDC was separated from user roles associated with permissions which implied a change of assigned roles of pre-configured users:

When upgrading from before v5.31.2, you may create such auth role and assign them to all users by

$ 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

and unassign previous user role from all users - except from regular user user - by

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

Not needed for upgrading from a PostgreSQL version with equal major version, e.g. from 15.4-31 to 15.6-32. s. PostgreSQL Documentation, Upgrading a PostgreSQL Cluster

Run new version of PostgreSQL Server, mounting the same host directories as used with the previous version, e.g.:

$ 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:16.4-33

If using Docker Compose adjust the version tags of the images in docker-compose.yaml accordingly, before starting the PostgreSQL Server by

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

Generally not needed for upgrading from a version which differs only in the third component of the version number (e.g. from 5.31.1 to 5.31.2). The only exception is for upgrading 5.31.0 to 5.31.1, for which you should create a missing index by

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

which can be already be applied on the running previous archive version.

Optionally backup database into a text file, by

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

To update from an older version than the most-recent previous version, e.g. from 5.30.x to 5.33.x, one has to apply the update scripts for the previous versions, e.g.:

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

before one can update PostgreSQL to the current version by:

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

You can minimize the downtime of the archive for the DB update, by performing the update of the DB schema into 3 steps:

The first:

$ docker exec postgres-container-name update-schema 5-33-1

can be already be applied on the running previous archive version.

You have to stop the archive, before applying the second step:

$ docker exec postgres-container-name update-schema 5-33-2

You can already start the new version of the archive, before applying the third step:

$ docker exec postgres-container-name update-schema 5-33-3

As long you did not applied the third step, you may fallback to the previous version of the archive, without reverting the update of the DB schema by the first and second step.

From v5.10.5 onwards, Keycloak is removed from the Archive Docker Images, but is now provided by a separate Docker image #916. So you have now start it separate from the Archive as described in Run secured archive services on a single host.

From v5.10.5 onwards, the Audit Record Repository Proxy is removed from the Archive Docker Image, and Keycloak Gatekeeper is provided as replacement by a separate Docker image. So you have now start it separate from the Archive as described in Run-secured-archive-services-and-Elastic-Stack-on-a-single-host.

From v5.16.1 onwards, the Wildfly Administration Console of the secured version of the Archive is also protected by Keycloak #1890. So you have to register the WildFly Administration Console as OIDC client in Keycloak as described in Run secured archive services on a single host and assign the role ADMINSTRATOR to users which shall be able to access the Wildfly Administration Console.

From v5.17.0 onwards, emitting of system logs to Logstash is configurable by environment variables. There are no longer dedicated Keycloak and Archive Docker Images (with Tag: VERSION-logstash) for that.

Run new version of DCM4CHEE Archive 5, mounting the same host directories as used with the previous version, e.g.:

$ 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.33.0

or using 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 rmi dcm4che/slapd-dcm4chee:2.6.6-32.0 dcm4che/dcm4chee-arc-psql:5.32.0 dcm4che/postgres-dcm4chee:16.2-32
Untagged: dcm4che/slapd-dcm4chee:2.6.6-32.0
Deleted: sha256:30d1bea543c13bccfd6e3186906ee8ef0cc1c723ca867923f78719c34549d717
Untagged: dcm4che/dcm4chee-arc-psql:5.32.0
Deleted: sha256:36ae24600c3163bd5725d9c00ddcc9c741b6dbdbdb677be55498ed5f66ecc658
Untagged: dcm4che/postgres-dcm4chee:16.2-32
Deleted: sha256:077b33ff659fc0994a4940da5bb34042cbe3f04c50fa409a5f6efe3f70091f88