Upgrade on Docker - amsalama/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.0, 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/ldap \
   -v /var/local/dcm4chee-arc/slapd.d:/etc/ldap/slapd.d \
   dcm4che/slapd-dcm4chee:2.6.2-26.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 # Note 1
$ docker exec prev-ldap export-account > /tmp/backup/account.ldif
$ docker stop prev-ldap

Note 1: 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.2-26.1
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, mounting the same host directories as used with the previous version. Take care to pass the hostname or IP address of the Archive by Environment Variable ARCHIVE_HOST, which is required for the new Study page, which depends on configured Web Applications, referring http(s) Network Connections, which Hostname must match the actual hostname or IP address of the Archive and not localhost! E.g.:

$ docker run --network=dcm4chee_default --name ldap \
           -p 389:389 \
           -e ARCHIVE_HOST=<archive-host> \
           -v /etc/localtime:/etc/localtime:ro \
           -v /etc/timezone:/etc/timezone:ro \
           -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.2-26.1

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

$ docker exec slapd-container-name update-data 5.25.1
$ docker exec slapd-container-name update-data 5.25.2
$ docker exec slapd-container-name update-data 5.26.0

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

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

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 afterwards 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

Not needed for upgrading from a PostgreSQL version with equal major version, e.g. from 14.1-25 to 14.2-26. 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:14.2-26

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

Not needed for upgrading from a version which differs only in the third component of the version number (e.g. from 5.25.1 to 5.25.2).

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

$ docker exec postgres-container-name update-schema 5.24
$ docker exec postgres-container-name update-schema 5.25

before one can update PostgreSQL to the current version by:

$ docker exec postgres-container-name update-schema 5.26
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.26-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.26-2

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

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

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.0-26.0 dcm4che/dcm4chee-arc-psql:5.26.0
Untagged: dcm4che/slapd-dcm4chee:2.6.0-26.0
Untagged: dcm4che/slapd-dcm4chee@sha256:bc998d1cfe6b99b24d330a6f3d63f6bce3e2a17185fb64e84aa533bc62fa0a8e
Deleted: sha256:10a1b7e59992ccf56123416f03a89bb1774a4275287284ec7b0c682b87b0a155
Deleted: sha256:f4472c8f20a9fe85e217326ba1f0855af57c92fa9b0ef14f1c2b653e43dcacc4
Deleted: sha256:17ee3ff643c6a3f027b3e2938de4b103caa648e8fc037da295875fa5b6815343
Deleted: sha256:1bf17fa2ca54538329f6352102aa645149cf8342be36c3ad26b9d0b8aa8eecb2
Deleted: sha256:4b0c50480aebb9f13b5d18d5d74e10d07c50e70ffe82de8db02f885af1d2c0e7
Deleted: sha256:31aafbed6824fbb6d886b265969674119015f0b938a753a87c2b4850794d3fbc
Deleted: sha256:32e56122d92b4972ecb88b916a2ff9fcbc27f3fe9a658d7837e993d787418f22
Deleted: sha256:18a2161a0a625d37e692850929a1953a456087c5d829f0eb3d19d2422a605366
Deleted: sha256:c1d4c32c92a9f7577c72e192e86c237b362309d4dbc0ce40c711e058dc04ce4d
Deleted: sha256:5e03d8cae8773cb694fff1d55da34a40d23c2349087ed15ce68476395d33753c
Untagged: dcm4che/dcm4chee-arc-psql:5.26.0
Untagged: dcm4che/dcm4chee-arc-psql@sha256:3e31b4e5a8f4041827b4397e33821cfbc640e560b1750ec137e4698932a2dd05
Deleted: sha256:e9b5ccc3e9a546b46720f9b3adc0846a3419f21c4db0e59233aeeab22770796c
Deleted: sha256:752aa1962072a0dd973b1879d197ef1af42ddff21cefbf6ce0084a8694d54996
Deleted: sha256:fcf2b1f8de4466ac242911a9ea0d680881c040106ec2b0fb8173c494bf91ba7c
Deleted: sha256:5c04e95b2c1bcf9a9996fa74dd1180fe389bc0854e28d160f3549b3131c288b3