Installation

Minimum System Requirements and Supporting Software

dcm4chee is a Java-based application for the management of digital clinical objects. As such, it should be run under the best hardware available for production systems. The minimal system configuration is as follows:

512 MB RAM
100 MB hard disk space (in addition to archive disk space for object storage and caching)
400 MHz CPU or better

dcm4chee requires a database to store transient and permanent information from the clinical workflow and objects. The authors of dcm4chee realize that database expertise varies from site to site, and has included support for several different databases for deployment with the archive. The list of supported databases is:

PostgreSQL 7.4+
MySQL 4.1.11+
Oracle 9i/10g
SQL Server
DB2 8.1+

Additional Software Notes

dcm4chee is a Java-based application. It requires the installation of the JDK version 1.4.2 or higher. JDK version 5 is recommended for the best performance and stability.

For image compression/decompression, dcm4chee 2.8.x utilizes Sun's Java Advanced Imaging (JAI) Image I/O Tools 1.0_01. The binary distribution packages of dcm4chee 2.8.x already includes the necessary JARs and native libraries for Windows and Linux i586. For Solaris support, you need to download the software package from Sun at http://java.sun.com/products/java-media/jai/downloads/download-iio-1_0_01.html and replace the Linux version of libclib_jiio.so in DCM4CHEE_DIST/bin/ with the file of the same name from the Solaris JAI Image IO distribution.

dcm4chee depends heavily on the JBoss (http://www.jboss.org) application server for its infrastructure. It is not necessary to download JBoss (as dcm4chee is pre-packaged within JBoss), but viewing the online (or downloaded) JBoss documentation will assist a great deal in learning the dcm4chee directory structure, and how the product operates under the covers. JBoss services such as XMBeans, JBossMQ (JMS), and EJB (Session and Entity beans) are utilized by dcm4chee.

Installation Steps

Installing dcm4chee is fairly easy:

Download the binary distribution of dcm4chee for the database of your choice from the Files page of the dcm4che project page on SourceForge (http://sourceforge.net/projects/dcm4che/). If you do not see a distribution for your database, you will have to build dcm4chee from the source code.
Once downloaded, extract the distribution package into your desired destination directory. Avoid using a directory path that contains spaces though, as that may cause problems when running the application from the command line.
Install the database software of your choice (keeping in mind the supported database systems) if you have not already done so. Keep in mind that the database software that you install (or have installed) must match the version of dcm4chee that you downloaded. For example, if you want to use PostgreSQL with dcm4chee then you should download the dcm4chee-standalone-psql-2.8.2.zip file from SourceForge.
If using a database other than MySQL or PostgreSQL you will need to copy an apropriate JDBC Driver for the database to DCM4CHEE_DIST/server/default/lib/. This is not necessary for MySQL or PostgreSQL because the binary distribution of dcm4chee already contains the correct JDBC drivers for these database systems.

Verify that your database installation has TCP/IP socket access available.

For example, with PostgreSQL you can check the pg_hba.conf file for your database:
$PGDATA/pg_hba.conf:
# IPv4 local connections:
host    all         all         127.0.0.1/32          trust
Then restart the postmaster service.

With Oracle, you can verify that the TNS Listener is enabled:
C:\>netstat -b -p TCP
Active Connections
  TCP    localhost:1284               host.domain.com:1521     ESTABLISHED     1788
  [ORACLE.EXE]

  TCP    localhost:1521               host.domain.com:1284     ESTABLISHED     1816
  [TNSLSNR.exe]

Initiate the archive database instance (named pacsdb) using the create DDL script located in DCM4CHEE_DIST/sql/create.xxx.
For example, with PostgreSQL on a Unix-based system:
```
> export PGUSER=postgres
> createdb pacsdb
> psql pacsdb \-f DCM4CHEE_DIST/sql/create.psql
```
To initialize a MySQL database on a Unix-based system:
```
> mysql \-uroot
mysql> create database pacsdb;
mysql> grant all on pacsdb.\* to 'pacs'@'localhost' identified by 'pacs';
mysql> \q
> mysql \-upacs \-ppacs < DCM4CHEE_DIST/sql/create.mysql
```
DDL Tuning

If you wish to take advantage of specific features of your RDBMS such as tablespaces, partitioning, etc. you will need to implement them on your own. This can sometimes be done with the tools that come with the database, or by modifying the DDL script before running it. If you make changes to the DDL script that you think might be useful to the wider audience, please submit them to the dcm4che-users listserv.

Adjust the dcm4chee database connection pool settings in DCM4CHEE_DIST/server/default/deploy/xxxx-ds.xmlto suit your environment. This includes the user name and password that the application should use when obtaining connections. In addition, JBoss allows for the configuration of other aspects of the connection pool. Although the default settings are fine for basic deployment scenarios, the following may be added to the XML file in order to tune the connection pool:

<\!\--example of how to specify class that determines if exception means connection should be destroyed-\->
<\!\--exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyExceptionSorter</exception-sorter-class-name-\->

<\!-\- this will be run before a managed connection is removed from the pool for use by a client-->
<\!--<check-valid-connection-sql>select * from something</check-valid-connection-sql> \-->

<\!-\- The minimum connections in a pool/sub-pool. Pools are lazily constructed on first use \-->
<min-pool-size>5</min-pool-size>

<\!-\- The maximum connections in a pool/sub-pool \-->
<max-pool-size>20</max-pool-size>

<\!-\- The time before an unused connection is destroyed \-->
<\!-\- NOTE: This is the check period. It will be destroyed somewhere between 1x and 2x this timeout after last use \-->
<idle-timeout-minutes>0</idle-timeout-minutes>

<\!-\- sql to call when connection is created
<new-connection-sql>some arbitrary sql</new-connection-sql>
 \-->

<\!-\- sql to call on an existing pooled connection when it is obtained from pool
<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
\-->

<\!-\- example of how to specify a class that determines a connection is valid before it is handed out from the pool
<valid-connection-checker-class-name>fully qualified name of class to use</valid-connection-checker-class-name>
\-->

<\!-\- Whether to check all statements are closed when the connection is returned to the pool,
 this is a debugging feature that should be turned off in production
<track-statements/>
\-->

Set the JAVA_HOME environment variable to your JDK installation directory.
Adjust the Java heap settings for the application
Windows: DCM4CHEE_DIST/bin/run.bat:
```
rem Sun JVM memory allocation pool parameters. Modify as appropriate.
set JAVA_OPTS=%JAVA_OPTS% \-Xms128m \-Xmx512m
```
Linux/Unix: DCM4CHEE_DIST/bin/run.conf
```
# Specify options to pass to the Java VM.
JAVA_OPTS="-server \-Xms64m \-Xmx200m \-Djava.awt.headless=true ..
```
Keep in mind the available RAM and memory requirements of other processes running on the hardware. For example, iif only 512 MB RAM is available on the machine, you should decrease the default value from -Xmx512m (on Windows to) -Xmx300.
Optional: Upon installation, all DICOM services are pre-configured with DCM4CHEE as the Application Entity Title (AE Title, or AET). Although it is possible to modify this default configuration at a later date through the Web-based administrative console, it is more efficient to replace DCM4CHEE with YOUR_AET in DCM4CHEE_DIST/server/default/conf/xmdesc/*.xml using utilities provided by your platform.
For example, on GNU Linux:
```
> find DCM4CHEE_DIST/server/default/conf/xmdesc \-exec \ sed \-i s/DCM4CHEE/YOUR_AET/g '{}' ';'
```
For dcm4chee 2.10.15:

- The above method of changing the AET is redundant in release 2.10.15. In fact, if you change the AET before installation by this method you may not be able to send dicom objects from the web interface.
- updateRetrieveAETitle() is a new MBean operation that has been added to the FileSystemMgt service of dcm4chee.archive. It simplifies the process by updating all the necessary fields, including the database.
- Access this via the JMX console at http://localhost:8080/jmx-console/HtmlAdaptor?action=inspectMBean&name=dcm4chee.archive%3Aservice%3DFileSystemMgt
Optional: You can configure the number of DICOM attributes stored in the database by modifying the attribute filter service at DCM4CHEE_DIST/server/default/conf/dcm4chee-attribute-filter.xml.
You're all done and ready to verify the installation (see below). After verifying that the application is installed and running correctly, you may want to install it as a Windows service or Unix daemon.
1. Stop the application (type ctrl-c in the console window).
2. Windows: install dcm4chee as a Windows service executing DCM4CHEE_DIST/bin/install_service.bat.
3. Redhat Linux:
  - Copy the init script DCM4CHEE_DIST/bin/dcm4chee_init_redhat.sh to /etc/init.d and adjust it according to the dcm4chee installation location, the JDK installation location, and which user the dcm4chee should run under. For convenience you can rename it to dcm4chee.
  - Add it to services by issuing chkconfig --add dcm4chee. now you can start and stop the server by service dcm4chee start and service dcm4chee stop (note that service dcm4chee restart will not work, because the starting will occur before the stopping is finished and thus there will be conflicts on ports etc.)
  - If you want dcm4chee to be started automatically on system startup, add it to appropriate runlevels (345) by chkconfig --level 345 dcm4chee on.

Verify the Installation

Navigate to the DCM4CHEE_DIST/bin directory, and execute the run.bat or run.sh script, as appropriate for your operating system. Your output should look like the following and contain no error or exception messages:

===============================================================================
.
 JBoss Bootstrap Environment
.
 JBOSS_HOME: C:\apps\dcm4chee-standalone-psql-2.8.2\bin
\\
..
.
 JAVA: C:\jdk1.5.0_06\bin\java
.
 JAVA_OPTS:  \-Dprogram.name=run.bat \-Xms128m \-Xmx512m
.
 CLASSPATH: C:\jdk1.5.0_06\lib\tools.jar;
 C:\apps\dcm4chee-standalone-psql-2.8.2\bin
\\
run.jar
.
===============================================================================
.
14:46:16,046 INFO [Server] Starting JBoss (MX MicroKernel)...
14:46:16,046 INFO [Server] Release ID: JBoss [Zion] 4.0.3SP1 (build:
 CVSTag=JBoss_4_0_3_SP1 date=200510231054)
...
...
...
14:46:50,626 INFO  \-> [JkMain] Jk running ID=0 time=0/60  config=null
14:46:50,636 INFO  \-> [Server] JBoss (MX MicroKernel) \[4.0.3SP1 (build:
 CVSTag=JBoss_4_0_3_SP1 date=200510231054)\] Started in 34s:580ms

Connect to the Web-based User Interface (default URL is http://localhost:8080/dcm4chee-web/) of the archive using any Web Browser (most tested are Mozilla Firefox and Microsoft Internet Explorer v6.x). You should get the User Login Screen. Login in using the default Administrator account admin, with password admin.
Connect to the JBoss JMX Console (default URL is http://localhost:8080/jmx-console/) and login in using the default Administrator account admin, with password admin.
Follow the link service=FileSystemMgt to the File System Management service configuration page under the dcm4chee.archive heading.
Invoke the operation addOnlineFileSystem(), with a directory path argument specifying where the archive shall store received objects/images.

Default Storage

If no Storage File System is configured, the archive will auto-configure DCM4CHEE_DIST/server/default/archive as the Storage File System when the the first object/image is received.
Optional: In the default configuration, received images are stored 'as is' - meaning that no compression is performed. Lossless (or other types of) compression of received uncompressed images can be activated by the CompressionRules attribute in the Storage SCP Service (service=StoreScp) configuration page. For example, set it to JLSL, to compress all types of images received from any Storage SCU with JPEG-LS Lossless codec. See the CODEC section of the dcm4che14 wiki space for more info on available compression options.
Optional: The directory used for caching generated JPEG representations of archived images requested by Web Access to DICOM Persistent Objects (WADO)can be specified by the CacheRoot attribute in the the WADO Service (service=WADOService) configuration page. Default: DCM4CHEE_DIST/server/default/wadocache.
The directory used for caching generated PDF representations of archived Structured Report Documents requested by IHE Retrieve Information for Display (RID) Services can be specified with the CacheRoot attribute in the RID Service (service=RIDService) configuration page. Default: DCM4CHEE_DIST/server/default/ihe_rid_cache.
Send some objects/images to the archive's Storage SCP, using the send utility of the dcm4che14 package, the dcm4che2 package, or another Storage SCU of your choice.
Refresh the Web Interface (http://localhost:8080/dcm4chee-web/), which should now show the the list of received studies.
Expand a study row to show contained series. Expand one of these series to show contained instances. In the case of images, you can follow the image icon on the right to invoke an HTTP WADO request for a JPEG presentation of this image which will be displayed in a separate browser window.
To test object retrieval, you will need an external Storage SCP acting as the Destination using the DICOM Receiver utility of the dcm4che14 package, the dcm4che2 package, or another Storage SCP of your choice.
Before initiating the retrieve, you will need to configure an additional Application Entity (AE) Title identifying your Move Destination using the "AE Management" function of the Web User Interface. For example:
```
AE Title: DCMRCV
Hostname: localhost
Port:     11113
```
Switch back to the Study List (the Folder view) and mark studies to retrieve using the check box on the right. Select "DCMRCV" as the send destination in the combo box above and click on the send button left from it.
Alternatively, you could initiate a C-MOVE with the utility of your choice with DCMRCV as the destination AE Title.

If everything worked, you are ready to start using dcm4chee. If not, post your questions to the dcm4che-users listserv.