Skip to content

Upgrade on Docker

Jump to bottom Edit New page
Gunter Zeilinger edited this page Apr 25, 2024 · 15 revisions

Stop and remove containers with previous version

$ 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 previous Wildfly configuration and deployment

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.

Update LDAP schema and configuration data

Backup LDAP configuration data (required for upgrading from 2.4.44-Y.Y versions)

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.5-32.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!

Restore LDAP configuration data from backup (required for upgrading 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.5-32.0
62a9d986.01beefec 0x7f3fbc703b48 @(#) $OpenLDAP: slapd 2.6.2 (May  8 2022 09:18:01) $
        openldap
62a9d986.033a9a70 0x7f3fbc703b48 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=query-realms,ou=realm-management,dc=dcm4che,dc=org"
adding new entry "cn=query-clients,ou=realm-management,dc=dcm4che,dc=org"

Stop the container by CTRL+C.

Run new version of OpenLDAP Server

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.5-32.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

Update LDAP schema (not necessary, if the LDAP configuration data was restored from backup)

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

Update LDAP configuration

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.0 to 5.32.0, apply the update scripts for the previous versions, e.g.:

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

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

$ docker exec slapd-container-name update-data 5.32.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.1
$ 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

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.31.1
$ 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.31.2
$ 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.32.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.31.1
$ 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.31.2
$ 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.32.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:

Name Password Role(s)
root changeit auth
root
auditlog
ADMINISTRATOR
all roles specified by client realm-management
admin changeit auth
admin
user changeit auth
user

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

Upgrading PostgreSQL major version

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

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.2-32

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

Update PostgreSQL

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.29.x to 5.32.x, one has to apply the update scripts for the previous versions, e.g.:

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

before one can update PostgreSQL to the current version by:

$ docker exec postgres-container-name update-schema 5.32
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-32-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-32-2

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

$ docker exec postgres-container-name update-schema 5-32-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.

Run new version of DCM4CHEE Archive 5

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.32.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

(Optional) purge docker images of previous version

$ docker rmi dcm4che/slapd-dcm4chee:2.6.5-31.2 dcm4che/dcm4chee-arc-psql:5.31.2 dcm4che/postgres-dcm4chee:15.4-31
Untagged: dcm4che/slapd-dcm4chee:2.6.5-31.2
Untagged: dcm4che/slapd-dcm4chee@sha256:ef2514eaae10483945b46edd57cbddca33ddf7a769061d8dc3eae3b4485a7f4f
Deleted: sha256:282728d2b62553a09e48c6bfecabc0d54a1a3df9aa78529595ce13702d960bf0
Deleted: sha256:be6a6f2ba5d2e850a01fcdb1970633e85aeb839607542fe1c5decd381998be85
Deleted: sha256:0fff813cee7b5053f6061163e63d978f06bd55a1f507242a32fa04d43e4730a5
Deleted: sha256:cd179b3a486c1ed80a8b0ed3612d80a2af164ab59baf4159e79a4b48696eff79
Untagged: dcm4che/dcm4chee-arc-psql:5.31.2
Untagged: dcm4che/dcm4chee-arc-psql@sha256:0abd2492d9743ccbce3290e52fb085688bf4d2a287899bad14454e15336abc0d
Deleted: sha256:46f2197ece8c90a0e132a733f2c29b02b016440e43e7a9f2374c74b7aadcfcd6
Deleted: sha256:76c81f28fde414697d19df8c5756d5afc4a8b35802227ebab06309e584b328b3
Deleted: sha256:37c741e5d626b05eca5ed07764583a7fb992f191d63826f82fb30f1d490f5168
Deleted: sha256:f6ec5c7fa34b674e40dc1c3a2ff5c3fd890f81a915ad4312b845ac3ce6de5932
Untagged: dcm4che/postgres-dcm4chee:15.4-31
Untagged: dcm4che/postgres-dcm4chee@sha256:7e37a57e3fe6a65d30b4b63f7c3d6ab058bbdd6e42e4b69d8828acb7d59e1727
Deleted: sha256:afe32d070ccb3a75768c717bae3dd0bd214869d35359f0351cd1297d3d11d68d
Add a custom footer

DCM4CHEE 5 Documentation

Clone this wiki locally