Getting Started with DCM4CHEE XDS 2.0.2

Requirements

Java SE 6 or later - tested with OpenJDK and Oracle JDK
JBoss Application Server 7.1.1.Final
Supported SQL Database:
- MySQL 5.5
- PostgreSQL 9.2.1
- Firebird 2.5.1
- DB2 10.1
- Oracle 11g
- Microsoft SQL Server (not yet tested!)
LDAP Server - tested with
- OpenDJ 2.4.6,
- OpenLDAP 2.4.33 and
- Apache DS 2.0.0-M8.
Note: DCM4CHEE XDS 2.x also supports using Java Preferences as configuration backend. But because DCM4CHEE XDS does not yet contain a configuration front-end, you would have to edit configuration entries in the Java Preferences back-end manually, which is quit cumbersome and therefore not further described here.
LDAP Browser - Apache Directory Studio 1.5.3

Note: Because DCM4CHEE XDS 2.0.x does not yet contain a specific configuration front-end, the LDAP Browser is needed to modify the XDS configuration.

Download and extract binary distribution package

DCM4CHEE XDS 2.x binary distributions for different databases can be obtained from Sourceforge. Extract (unzip) your chosen download to the directory of your choice.

Initialize Database

MySQL

Enable remote access by commenting out skip-networking in configuration file my.conf.

Create database and grant access to user

 > mysql -u root -p<root-password>
 mysql> CREATE DATABASE <database-name>;
 mysql> GRANT ALL ON <database-name>.* TO '<user-name>' IDENTIFIED BY '<user-password>';
 mysql> quit

Create tables and indexes

 > mysql -u <user-name> -p<user-password> < $DCM4CHEE_XDS2/sql/create-table-mysql.ddl
 > mysql -u <user-name> -p<user-password> < $DCM4CHEE_XDS2/sql/create-index.ddl

PostgreSQL

Create user with permission to create databases

 > createuser -U postgres -P -d <user-name>
 Enter password for new role: <user-password> 
 Enter it again: <user-password>

Create database

 > createdb -U <user-name> <database-name>

Create tables and indexes

 > psql -U <user-name> < $DCM4CHEE_XDS2/sql/create-table-psql.ddl
 > psql -U <user-name> < $DCM4CHEE_XDS2/sql/create-index.ddl

Firebird

Define database name in configuration file aliases.conf:
```
 <database-name> = <database-file-path>
```

Create user

 > gsec -user sysdba -password masterkey \
   -add <user-name> -pw <user-password>

Create database, tables and indexes

 > isql 
 Use CONNECT or CREATE DATABASE to specify a database
 SQL> CREATE DATABASE 'localhost:<database-name>'
 CON> user '<user-name>' password '<user-password>';
 SQL> IN $DCM4CHEE_XDS2/sql/create-table-firebird.ddl;
 SQL> IN $DCM4CHEE_XDS2/sql/create-index.ddl;
 SQL> EXIT;

DB2

Create database and grant authority to create tables to user (must match existing OS user)

 > sudo su db2inst1
 > db2
 db2 => CREATE DATABASE <database-name> PAGESIZE 16 K
 db2 => connect to <database-name>
 db2 => GRANT CREATETAB ON DATABASE TO USER <user-name>
 db2 => terminate

Create tables and indexes

 > su <user-name>
 Password: <user-password>
 > db2 connect to <database-name>
 > db2 -t < $DCM4CHEE_XDS2/sql/create-table-db2.ddl
 > db2 -t < $DCM4CHEE_XDS2/sql/create-index.ddl
 > db2 terminate

Oracle 11g

TODO

Setup LDAP Server

OpenDJ

Copy LDAP schema files for OpenDJ from DCM4CHEE XDS 2.x distribution to OpenDJ schema configuration directory:

> cp $DCM4CHEE_XDS2/ldap/opendj/* $OPENDJ_HOME/config/schema/ [UNIX]
> copy %DCM4CHEE_XDS2%\ldap\opendj\* %OPENDJ_HOME%\config\schema\ [Windows]

Run OpenDJ GUI based setup utility
```
> $OPENDJ_HOME/setup
```
Log the values choosen for
- LDAP Listener port (1389)
- Root User DN (cn=Directory Manager)
- Root User Password (secret)
- Directory Base DN (dc=example,dc=com)
needed for the LDAP connection configuration of DCM4CHEE XDS 2.x.

After initial setup, you may start and stop OpenDJ by

 > $OPENDJ_HOME/bin/start-ds
 > $OPENDJ_HOME/bin/stopt-ds

OpenLDAP

OpenLDAP binary distributions are available for most Linux distributions and for Windows.

OpenLDAP can be alternatively configured by

slapd.conf configuration file
dynamic runtime configuration

OpenLDAP with slapd.conf configuration file

Copy LDAP schema files for OpenLDAP from DCM4CHEE XDS 2.x distribution to OpenLDAP schema configuration directory:

> cp $DCM4CHEE_XDS2/ldap/schema/* /etc/openldap/schema/ [UNIX]
> copy %DCM4CHEE_XDS2%\ldap\schema\* \Program Files\OpenLDAP\schema\ [Windows]

Add references to schema files in slapd.conf, e.g.:

include         /etc/openldap/schema/core.schema
include         /etc/openldap/schema/dicom.schema
include         /etc/openldap/schema/dcm4che.schema
include         /etc/openldap/schema/dcm4che-hl7.schema
include         /etc/openldap/schema/dcm4chee-xds2.schema

You may also change the default values for

suffix          "dc=my-domain,dc=com"
rootdn          "cn=Manager,dc=my-domain,dc=com"
rootpw          secret

in slapd.conf.

OpenLDAP with dynamic runtime configuration

Import LDAP schema files for OpenLDAP runtime configuration, binding as root user of the config backend, using OpenLDAP CL utility ldapadd, e.g.:

> ldapadd -xW -Dcn=config -f $DCM4CHEE_XDS2/ldap/slapd/dicom.ldif
> ldapadd -xW -Dcn=config -f $DCM4CHEE_XDS2/ldap/slapd/dcm4che.ldif
> ldapadd -xW -Dcn=config -f $DCM4CHEE_XDS2/ldap/slapd/dcm4che-hl7.ldif
> ldapadd -xW -Dcn=config -f $DCM4CHEE_XDS2/ldap/slapd/dcm4chee-xds2.ldif

If you don't know the root user and its password of the config backend, you may look into /etc/openldap/slap.d/cn=config/olcDatabase={0}config.ldif:

olcRootDN: cn=config
olcRootPW:: VmVyeVNlY3JldA==

and decode the base64 decoded password, e.g:

> echo -n VmVyeVNlY3JldA== | base64 -d
VerySecret

or specify a new password in plan text, e.g:

olcRootPW: VerySecret

Directory Base DN and Root User DN can be modified by changing the values of attributes

olcSuffix: dc=my-domain,dc=com
olcRootDN: cn=Manager,dc=my-domain,dc=com

of object olcDatabase={1}bdb,cn=config by specifing the new values in a LDIF file (e.g. modify-baseDN.ldif)

dn: olcDatabase={1}bdb,cn=config
changetype: modify
replace: olcSuffix
olcSuffix: dc=example,dc=com
-
replace: olcRootDN
olcRootDN: cn=Manager,dc=example,dc=com
-

and applying it using OpenLDAP CL utility ldapmodify, e.g.:

> ldapmodify -xW -Dcn=config -f modify-baseDN.ldif

Apache DS 2.0

Install Apache DS 2.0.0-M8 on your system and start Apache DS.

Install Apache Directory Studio 1.5.3 and create a new LDAP Connection with:

Network Parameter:
    Hostname: localhost
    Port:     10398
Authentication Parameter:
    Bind DN or user: uid=admin,ou=system
    Bind password:   secret

Import LDAP schema files for Apache DS:

$DCM4CHEE_XDS2/ldap/apacheds/dicom.ldif
$DCM4CHEE_XDS2/ldap/apacheds/dcm4che.ldif
$DCM4CHEE_XDS2/ldap/apacheds/dcm4che-hl7.ldif
$DCM4CHEE_XDS2/ldap/apacheds/dcm4chee-xds2.ldif

using the LDIF import function of Apache Directory Studio LDAP Browser.

You may modify the default Directory Base DN dc=example,dc=com by changing the value of attribute
```
ads-partitionsuffix: dc=example,dc=com`
```
of object
```
ou=config
+ ads-directoryServiceId=default
  + ou=partitions
      ads-partitionId=example
```
using Apache Directory Studio LDAP Browser.

Import sample configuration into LDAP Server

If not alread done, install Apache Directory Studio 1.5.3 and create a new LDAP Connection corresponding to your LDAP Server configuration, e.g:

Network Parameter:
    Hostname: localhost
    Port:     1398
Authentication Parameter:
    Bind DN or user: cn=Directory Manager
    Bind password:   secret
Browser Options:
    Base DN: dc=example,dc=com

If you configured a different Directory Base DN thandc=example,dc=com, you have to replace all occurrences of dc=example,dc=com in LDIF files

$DCM4CHEE_XDS2/ldap/init-baseDN.ldif
$DCM4CHEE_XDS2/ldap/init-config.ldif
$DCM4CHEE_XDS2/ldap/sample-config.ldif

by your Directory Base DN, e.g.:

> cd $DCM4CHEE_XDS2/ldap
> sed -i s/dc=example,dc=com/dc=my-domain,dc=com/ init-baseDN.ldif
> sed -i s/dc=example,dc=com/dc=my-domain,dc=com/ init-config.ldif
> sed -i s/dc=example,dc=com/dc=my-domain,dc=com/ sample-config.ldif

If there is not already a base entry in the directory data base, import $DCM4CHEE_XDS2/ldap/init-baseDN.ldif using the LDIF import function of Apache Directory Studio LDAP Browser.
If there are not already DICOM configuration root entries in the directory data base, import $DCM4CHEE_XDS2/ldap/init-config.ldif using the LDIF import function of Apache Directory Studio LDAP Browser.
Import $DCM4CHEE_XDS2/ldap/sample-config.ldif using the LDIF import function of Apache Directory Studio LDAP Browser.
By default configuration, the HL7 service of DCM4CHEE XDS2 registry does not accept remote connections. To enable remote connections, replace the value of attribute
```
dicomHostname=localhost
```
of the 2 dicomNetworkConnection objects
```
dc=example,dc=com
+ cn=XDS Configuration
  + cn=Devices
    + dicomDeviceName=dcm4chee-xds2-registry
        cn=hl7
        cn=hl7-tls
```
by the actual hostname of your system, using Apache Directory Studio LDAP Browser.

Setup JBoss AS 7

Adjust DCM4CHEE XDS2 LDAP Connection configuration file $DCM4CHEE_ARC/configuration/dcm4chee-xds2/ldap.properties:

java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory
java.naming.ldap.attributes.binary=dicomVendorData
java.naming.provider.url=ldap://localhost:1389/dc=example,dc=com
java.naming.security.principal=cn=Directory Manager
java.naming.security.credentials=secret

to your LDAP Server configuration.

Install required libraries as JBoss AS 7 modules:

Install DCM4CHE 3.3.1 libraries as JBoss AS 7 module:

    cd  $JBOSS_HOME
    unzip $DCM4CHEE_XDS2/jboss-module/dcm4che-jboss-modules-3.3.1.zip

Install QueryDSL 3.2.3 libraries as JBoss AS 7 module:

    cd  $JBOSS_HOME
    unzip $DCM4CHEE_XDS2/jboss-module/querydsl-jboss-modules-3.2.3.zip

Install XDS command line tools

Install DCM4CHEE XDS2 tools libraries as JBoss AS 7 module:

    cd  $JBOSS_HOME
    cp -r $DCM4CHEE_XDS2/modules .

Install shellscripts:

    cd  $JBOSS_HOME
    cp -r $DCM4CHEE_XDS2/bin .

Install JDBC Driver. DCM4CHEE XDS 2.x binary distributions do not include a JDBC driver for the database for license issues. You may download it from:
- MySQL
- PostgreSQL
- Firebird
- DB2, also included in DB2 Express-C
- Oracle, also included in Oracle 11g XE)
- Microsoft SQL Server
The JDBC driver can be installed either as a deployment or as a core module. See

Installation as deployment is limited to JDBC 4-compliant driver consisting of one JAR.

For installation as a core module, $DCM4CHEE_XDS2/jboss-module/jdbc-jboss-modules-1.0.0-<database>.zip already provides a module definition file module.xml. You just need to extract the ZIP file into $JBOSS_HOME and copy the JDBC Driver file(s) into the sub-directory, e.g.:
```
> cd $JBOSS_HOME
> unzip $DCM4CHEE_XDS2/jboss-module/jdbc-jboss-modules-1.0.0-db2.zip
> cd $DB2_HOME/java
> cp db2jcc4.jar db2jcc_license_cu.jar $JBOSS_HOME/modules/com/ibm/db2/main/
```
Verify, that the actual JDBC Driver file(s) name matches the path(s) in the provided module.xml, e.g.:
```
 <?xml version="1.0" encoding="UTF-8"?>
 <module xmlns="urn:jboss:module:1.1" name="com.ibm.db2">
     <resources>
         <resource-root path="db2jcc4.jar"/>
         <resource-root path="db2jcc_license_cu.jar"/>
     </resources>
 
     <dependencies>
         <module name="javax.api"/>
         <module name="javax.transaction.api"/>
     </dependencies>
 </module>
```

Start JBoss AS 7 in standalone mode with the Java EE 6 Full Profile configuration. To preserve the original JBoss AS 7 configuration you may copy the original configuration file for JavaEE 6 Full Profile:

> cd $JBOSS_HOME/standalone/configuration/
> cp standalone-full.xml dcm4chee-xds2.xml

and start JBoss AS 7 specifying the new configuration file:

> $JBOSS_HOME/bin/standalone.sh -c dcm4chee-xds2.xml [UNIX]
> %JBOSS_HOME%\bin\standalone.bat -c dcm4chee-xds2.xml [Windows]

Verify, that JBoss AS 7 started successfully, e.g.:

=========================================================================

  JBoss Bootstrap Environment

  JBOSS_HOME: /home/gunter/jboss7

  JAVA: /usr/lib/jvm/java-6-openjdk/bin/java

  JAVA_OPTS:  -server -XX:+UseCompressedOops -XX:+TieredCompilation ...

=========================================================================

13:01:48,788 INFO  [org.jboss.modules] JBoss Modules version 1.1.1.GA
13:01:48,926 INFO  [org.jboss.msc] JBoss MSC version 1.0.2.GA
13:01:48,969 INFO  [org.jboss.as] JBAS015899: JBoss AS 7.1.1.Final "Brontes" starting
:
13:01:51,239 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS 7.1.1.Final "Brontes" started ...

Running JBoss AS 7 in domain mode should work, but was not yet tested.

Add JDBC Driver into the server configuration using JBoss AS 7 CLI in a new console window:

> $JBOSS_HOME/bin/jboss-cli.sh -c [UNIX]
> %JBOSS_HOME%\bin\jboss-cli.bat -c [Windows]
[standalone@localhost:9999 /] /subsystem=datasources/jdbc-driver=<driver-name>:add(driver-module-name=<module-name>,driver-name=<driver-name>)

You may choose any <driver-name> for the JDBC Driver, <module-name> must match the name defined in the module definition file module.xml of the JDBC driver, e.g.:

[standalone@localhost:9999 /] /subsystem=datasources/jdbc-driver=db2:add(driver-module-name=com.ibm.db2,driver-name=db2)

Create and enable a new Data Source bound to JNDI name java:/xdsDS using JBoss AS 7 CLI:
```
[standalone@localhost:9999 /] data-source add --name=xdsDS \
>     --driver-name=<driver-name> \
>     --connection-url=<jdbc-url> \
>     --jndi-name=java:/xdsDS \
>     --user-name=<user-name> \
>     --password=<user-password>
[standalone@localhost:9999 /] data-source enable --name=xdsDS
```
The format of <jdbc-url> is JDBC Driver specific, e.g.:
- MySQL: jdbc:mysql://localhost:3306/<database-name>
- PostgreSQL: jdbc:postgresql://localhost:5432/<database-name>
- Firebird: jdbc:firebirdsql:localhost/3050:<database-name>
- DB2: jdbc:db2://localhost:50000/<database-name>
- Oracle: jdbc:oracle:thin:@localhost:1521:<database-name>
- Microsoft SQL Server: jdbc:sqlserver://localhost:1433;databaseName=<database-name>
At default, DCM4CHEE XDS 2.x will use Java Preferences as configuration backend.

You can enable LDAP configuration backend by setting system property org.dcm4chee.xds.ldapPropertiesURL using JBoss AS 7 CLI:
```
 [standalone@localhost:9999 /] /system-property=org.dcm4chee.xds.ldapPropertiesURL:add(value=<url>)
```
At default, DCM4CHEE XDS 2.x will assume dcm4chee-xds as its Device Name, used to find its configuration in the configuration backend (LDAP Server or Java Preferences). You may specify a different Device Name by system property org.dcm4chee.xds.deviceName using JBoss AS 7 CLI:
```
 [standalone@localhost:9999 /] /system-property=org.dcm4chee.xds.deviceName:add(value=<device-name>)
```
If several XDS Services (Registry, Repository, XCA, XCA-I) are deployed on one JBoss instance, the configuration can be either all in one device or splitted in several devices.

To use different devicenames for each XDS service, following system properties can be used to specify service dependent devicenames:
```
 Registry   : org.dcm4chee.xds.devicename.registry
 Repository : org.dcm4chee.xds.devicename.repository
 XCA        : org.dcm4chee.xds.devicename.xca
 XCA-I      : org.dcm4chee.xds.devicename.xca-i
```

Deploy DCM4CHEE XDS 2.x services using JBoss AS 7 CLI, e.g.:

[standalone@localhost:9999 /] deploy $DCM4CHEE_XDS2/deploy/dcm4chee-xds2-registry-ear-2.0.2-<database-name>.ear
[standalone@localhost:9999 /] deploy $DCM4CHEE_XDS2/deploy/dcm4chee-xds2-repository-ear-2.0.2-<database-name>.ear
[standalone@localhost:9999 /] deploy $DCM4CHEE_XDS2/deploy/dcm4chee-xds2-xca-ear-2.0.2-<database-name>.ear
[standalone@localhost:9999 /] deploy $DCM4CHEE_XDS2/deploy/dcm4chee-xds2-xcai-ear-2.0.2-<database-name>.ear

Verify that DCM4CHEE XDS service was deployed and started successfully, e.g.:

You may undeploy DCM4CHEE XDS services at any time using JBoss AS 7 CLI, e.g.:

[standalone@localhost:9999 /] undeploy dcm4chee-xds2-registry-ear-2.0.2-<database-name>.ear

Initialize XDS Registry with ebXML Classifications and Associations defined by XDS:

a) Default XDS configuration on default local installation

> $JBOSS_HOME/bin/xdsinit.sh [UNIX]
> %JBOSS_HOME%\bin\xdsinit.bat [Windows]

b) Default XDS configuration on user specific (different port) or remote installation

e.g.: initialize XDS Registry on host 'xdsserver' port 8180 with defaults:
> $JBOSS_HOME/bin/xdsinit.sh -wsdl http://xdsserver:8180/XDSbRegistry?wsdl [UNIX]
> %JBOSS_HOME%\bin\xdsinit.bat -wsdl http://xdsserver:8180/XDSbRegistry?wsdl [Windows]

c) Add new ebXML Classifications and Associations given by XML files (SubmitObjectRequest)

> $JBOSS_HOME/bin/xdsinit.sh <filename1> [<filename2> [..]] [UNIX]
> %JBOSS_HOME%\bin\xdsinit.bat <filename1> [<filename2> [..]] [Windows]

Each XDS service comes with a RESTful controller service to reload / show configuration

 Registry   : http://<host>:<port>/xds-reg-rs/ctrl/config
 Repository : http://<host>:<port>/xds-rep-rs/ctrl/config
 XCA        : http://<host>:<port>/xca-rs/ctrl/config
 XCA-I      : http://<host>:<port>/xcai-rs/ctrl/config

XDS registry comes with an administration web-app that allows to browse the registry contents and perform some basic administration (delete document entries, modify metadata, etc.). The web-interface is accessible at http://<host>:<port>/xds-browser. To allow a user to use the web-app, assign him/her the WebAdmin role in dcm4chee realm.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

INSTALL.md

INSTALL.md

Getting Started with DCM4CHEE XDS 2.0.2

Requirements

Download and extract binary distribution package

Initialize Database

MySQL

PostgreSQL

Firebird

DB2

Oracle 11g

Setup LDAP Server

OpenDJ

OpenLDAP

OpenLDAP with slapd.conf configuration file

OpenLDAP with dynamic runtime configuration

Apache DS 2.0

Import sample configuration into LDAP Server

Setup JBoss AS 7

Testing DCM4CHEE XDS 2.x

Files

INSTALL.md

Latest commit

History

INSTALL.md

File metadata and controls

Getting Started with DCM4CHEE XDS 2.0.2

Requirements

Download and extract binary distribution package

Initialize Database

MySQL

PostgreSQL

Firebird

DB2

Oracle 11g

Setup LDAP Server

OpenDJ

OpenLDAP

OpenLDAP with slapd.conf configuration file

OpenLDAP with dynamic runtime configuration

Apache DS 2.0

Import sample configuration into LDAP Server

Setup JBoss AS 7

Testing DCM4CHEE XDS 2.x