How to install and setup a PACS (dcm4chee)


Picture Archiving and Communication System (PACS) is a medical imaging technology which provides economical storage of and convenient access to images from multiple modalities (source machine types).

In our case we can use it to create pre-production environments to test PACS communications. For example, we can setup a PACS to send endoscopy images and retrieve radiology samples to an application.

We are going to use the dcm4chee open source solution from This is a JEE and JMX system which is deployed within the JBoss Application Server to provide a number of clinical services. It may be used for a variety of different purposes, the most popular being:

  1. a DICOM archive and image manager
  2. a PACS, when coupled with a viewer such as OsiriXK-PACSClearCanvasGinkgo CADx, etc.

As a host, trying to use always open source solutions, we are going to use a GNU/Linux operating system, specifically Kubuntu 14.04 LTS (Long Term Supported).

 As a database we are going to use PostgresSQL (9.3).

We can find installation instructions at dcm4chee page, but there are not always updated, so I will show all the steps for the current versions.

Installation of JDK

Although we can use the openjdk that comes with kubuntu, we are going to use the one from Oracle.

First we have to download the package from Oracle site:

And choose the one that fits our platform (x86 tar.gz in my case)

2014-11-27 17_19_48-Java SE Development Kit 8 - Downloads

Once decrompressed, just copy the folder to /usr/lib and add the following lines at the end of the ~/.bashrc file:

export JAVA_HOME
export PATH

We can check the version using the command “java -version”

$ java -version
java version “1.8.0_25”
Java(TM) SE Runtime Environment (build 1.8.0_25-b17)
Java HotSpot(TM) Server VM (build 25.25-b02, mixed mode)

Installation procedure

1. Download and extract the binary distribution package of dcm4chee:

We have to download the latest version of dcm4chee that is relevant to the database we want from sourceforgeIn our case, the postgres one.

2014-11-27 17_39_40-dcm4che, a DICOM Implementation in JAVA - Browse _dcm4chee_2.18

2. Download the binary distribution package of JBoss Application Server 4.2.3.GA

Download the binary distribution of JBoss 4.2.3.GA from here and extract it into a different directory.

Use neither JBoss 5 nor JBoss 6, because it is completely re-architected and is significantly different than the 4.2 line of JBoss! 

If you want to use JDK 5, don’t download JBoss for JDK 6 ( – use!

3. Copy files from JBoss to dcm4chee

Go to the dcm4chee-2.18.1-xxx/bin directory and execute the script, with the path of your JBoss as installation directory as a parameter.

For example, if we have JBoss downloaded in the same directory as dcm4chee:

dcm4chee-2.18.0-psql/bin$ sh ../../jboss-4.2.3.GA/

4. Install the Database Software and create the DCM4CHEE Database

Set permissions on Postgres database. The following setting will trust only connections from the localhost, which is reasonable for a development machine, but may need to be changed for production.

Edit the pg_hba.conf file in order to set the right permissions.

$ sudo vim /etc/postgresql/9.3/main/pg_hba.conf

Set a password for the postgres user

$export PGUSER=postgres
$createdb pacsdb
$psql pacsdb -f dcm4chee-psql-2.18.0/sql/create.psql

This will create all the database structure. Now we have to setup the database access from dcm4chee. In your dcm4chee installation, use a text editor to edit server/default/deploy/pacs-postgres-ds.xml and set the database password. This file controls the dcm4chee connections to the main archive application database.PostgressPWD

5. Deploy the Audit Record Repository (ARR)

The Audit Record Repository will help us track any movement in dcm4chee.

Starting with dcm4chee-2.12.0, the binary distribution package of the archive application does NOT include the dcm4chee Audit Record Repository (ARR) anymore. The ARR maintains an audit log of all transactions within the archive. This is necessary for HIPAA and IHE. Some dcm4chee deployment scenarios call for the deployment of the ARR in a standalone fashion because it acts as an ARR for more than one dcm4chee instance, or multiple applications which can take advantage of an external ARR. Commonly though it is deployed within the dcm4chee archive itself.

Download the latest version from soruceforge related with the database we have chosen (postgres in our case)

2014-11-27 19_28_29-dcm4che, a DICOM Implementation in JAVA - Browse _dcm4chee-arr_3.0

Go to the dcm4chee-*-xxx/bin directory and execute the script with the path of the dcm4chee-arr-* installation directory as parameter.

NOTE: Due to a bug, we have to modify two lines of the installer dcm4chee-2.18.psql/bin/

VERS=3.0.11 should be VERS=3.0.12


cp -v “$ARR_SERV” /lib/dcm4che-core-2.0.25.jar \ should be cp -v “$ARR_SERV” /lib/dcm4che-core-2.0.27.jar \


Now we can run the installer without problem.

dcm4chee-2.18.0-psql/bin$ sh ../../dcm4chee-arr-3.0.12-psql/

We have to create the arr database in Postgres and create the structure using the script from the dcm4chee-arr sql folder:

dcm4chee-arr-3.0.12-psql/sql$ psql arrdb -f dcm4chee-arr-psql.ddl

Now we have to set the ARR database acces. In your dcm4chee installation, use a text editor to edit server/default/deploy/arr-psql-ds.xml and set the database password. This file control the dcm4chee connections to the Audit Record Repository (ARR) database.


6. Set environment variable JAVA_HOME to JDK location

The dcm4chee startup/shutdown scripts depend on the JAVA_HOME environment variable in order to find the Java executables and libraries. For example, if your JDK is installed at “/usr/lib/jvm/jdk1.8.0_25” then that is the path to JAVA_HOME.

If you choose to add in the ~/.bashrc file, remember the PACS would not start unless you start the session.

7. Optional: Adjust maximum allocation of heap memory

Java programs run with a finite amount of memory allocated to them. If you anticipate high volumes of storage and retrievals, or very large datasets, you may want to increase the max (-Xmx) heap size of the Java process.

Linux/Unix/OSX: dcm4chee-2.xx-xxx/bin/run.conf

# Specify options to pass to the Java VM.
if [ "x$JAVA_OPTS" = "x" ]; then
JAVA_OPTS="-Xms128m -Xmx512m -XX:MaxPermSize=128m ..

according to available RAM and memory requirements of other processes on this node.

E.g.: if only 512 MB RAM are available, you should decrease the default value -Xmx512m to (e.g.) -Xmx300.

8. Test the installation

To test your installation, go to the dcm4chee-2.xx-xxx/bin directory and execute the script. Your output should look like the following and contains no error or exception messages:

 JBoss Bootstrap Environment
 JBOSS_HOME: /home/daniel/Downloads/dcm4chee-2.18.0-psql
 JAVA: /usr/lib/jvm/jdk1.8.0_25/bin/java
 JAVA_OPTS: -server -Xms128m -Xmx512m -XX:MaxPermSize=128m -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djboss.messaging.ServerPeerID=0 -Djava.awt.headless=true -Djava.library.path=/home/daniel/Downloads/dcm4chee-2.18.0-psql/bin/native
 CLASSPATH: /home/daniel/Downloads/dcm4chee-2.18.0-psql/bin/run.jar:/usr/lib/jvm/jdk1.8.0_25/lib/tools.jar
Java HotSpot(TM) Server VM warning: ignoring option MaxPermSize=128m; support was removed in 8.0
19:43:15,087 INFO [Server] Starting JBoss (MX MicroKernel)...
19:43:15,088 INFO [Server] Release ID: JBoss [Trinity] 4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200807181439)
19:43:15,089 INFO [Server] Home Dir: /home/daniel/Downloads/dcm4chee-2.18.0-psql
19:43:15,089 INFO [Server] Home URL: file:/home/daniel/Downloads/dcm4chee-2.18.0-psql/
19:43:15,090 INFO [Server] Patch URL: null
19:43:15,090 INFO [Server] Server Name: default
19:43:15,090 INFO [Server] Server Home Dir: /home/daniel/Downloads/dcm4chee-2.18.0-psql/server/default
19:43:15,090 INFO [Server] Server Home URL: file:/home/daniel/Downloads/dcm4chee-2.18.0-psql/server/default/
19:43:15,090 INFO [Server] Server Log Dir: /home/daniel/Downloads/dcm4chee-2.18.0-psql/server/default/log
19:43:15,090 INFO [Server] Server Temp Dir: /home/daniel/Downloads/dcm4chee-2.18.0-psql/server/default/tmp
19:43:15,091 INFO [Server] Root Deployment Filename: jboss-service.xml
19:43:15,359 INFO [ServerInfo] Java version: 1.8.0_25,Oracle Corporation
19:43:15,359 INFO [ServerInfo] Java VM: Java HotSpot(TM) Server VM 25.25-b02,Oracle Corporation
19:43:15,359 INFO [ServerInfo] OS-System: Linux 3.13.0-40-generic,i386
19:43:15,654 INFO [Server] Core system initialized
19:43:17,680 INFO [WebService] Using RMI server codebase: http://daniel-VirtualBox:8083/
19:43:17,682 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resource:jboss-log4j.xml
19:43:18,095 INFO [TransactionManagerService] JBossTS Transaction Service (JTA version) - JBoss Inc.
19:43:49,281 INFO [RequestListenerInterface] registered listener interface [RequestListenerInterface name=IActivePageBehaviorListener, method=public abstract void org.apache.wicket.behavior.IBehaviorListener.onRequest()]
19:43:49,281 INFO [Application] [WicketApplication] init: Wicket extensions initializer
19:43:49,281 INFO [WebApplication] [WicketApplication] Started Wicket version 1.4.22 in deployment mode
19:43:49,347 INFO [EARDeployer] Started J2EE application: file:/home/daniel/Downloads/dcm4chee-2.18.0-psql/server/default/deploy/dcm4chee-web-ear-3.0.4-psql.ear
19:43:49,378 INFO [ServerImpl] Start Server listening on
19:43:49,414 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-
19:43:49,440 INFO [Http11Protocol] Starting Coyote HTTP/1.1 on http-8443
19:43:49,460 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-
19:43:49,472 INFO [ServerImpl] Start Server listening on
19:43:49,473 INFO [Server] JBoss (MX MicroKernel) [4.2.3.GA (build: SVNTag=JBoss_4_2_3_GA date=200807181439)] Started in 34s:379ms

9. Login into web interface

Connect to the Web Interface at http://localhost:8080/dcm4chee-web3/ of the archive using any Web Browser. You should get the User Login Screen. Login in using default Administrator account ‘admin’, with password ‘admin’.

2014-11-28 08_09_43-dcm4chee Login

2014-11-28 08_10_49-dcm4chee after login

10. Login to JMX Console

Connect to JBoss’s JMX Console at http://localhost:8080/jmx-console/ and login using also the Administrator account ‘admin’, with password ‘admin’.
Follow the link “group=ONLINE_STORAGE,service=FileSystemMgt” to the configuration page for File System Management service under the “dcm4chee.archive” heading.
Invoke the operation addRWFileSystem(), with argument dirPath specifying the directory, where the archive shall store received objects/images.

If no Storage File System is configured, the archive will auto-configure dcm4chee-2.xx.1-xxx/server/default/archive as Storage File System, when receiving the first object/image.

2014-11-28 08_11_35-dcm4chee logs

11. Optional: Change the default AE Title

Connect to JBoss’s JMX Console at http://localhost:8080/jmx-console/ and login using also the Administrator account ‘admin’, with password ‘admin’.

2014-11-28 08_12_25-dcm4chee Catalina

Follow the link “service=AE” to the configuration page for AE (Application Entity – a DICOM term for a DICOM node on the network) service under the “dcm4chee.archive” heading.
Invoke the operation update AETitle with the old AE Title (DCM4CHEE if unchanged from the default), and new AE Title as parameters.
This will update the following configurations:

  • update  the “retrieve AET” of file systems, associated to the current retrieve AET of this node
  • update “retrieve AETs” of all instances, series and studies that have files on these filesystems
  • update the entry for the “retrieve AE” in the AE Configuration
  • update the AE Title of all services listed by attribute OtherServiceAETitleAttributesToUpdate

12. Install as a service

If running as a service or daemon on any operating system, you should disable CONSOLE logging as noted here:ኳ

After verifying that the archive works, you may want to run it as a service so that it stays running even when you log out. If still running in the console window, you may stop the archive by Ctrl+C, and copy the init script to /etc/init.d/ and adjust it according your installation location of the archive and the JDK and under which user the archive application shall run.

16 thoughts on “How to install and setup a PACS (dcm4chee)”

  1. Felicitaciones por el artículo
    Te envié invitación por Linkedin ya que me dedico a Instalación y Soporte de DCM4CHEE

  2. Hi,
    I need help in installing DCM4CHEE.. I have downloaded and extracted all the above said files with the paths:
    but when i try to install jboss ,
    C:\apps\dcm4chee-2.18.3-mysql\bin>install_jboss.bat C:\apps\jboss-4.2.3.GA
    it shows
    ‘install_jboss.bat’ is not recognized as an internal or external command,
    operable program or batch file.

    Pls help me go forward

  3. Hi Daniel
    i sorted out the problem.. its becoz dcm4chee-2.18.3-mysql version doesnt have an install_jboss.bat file within the folder.. so i tried other version dcm4chee-2.18.1-mysql. Everything seems ok until i reached the verification test. when i execute run.bat it shows error ( I am using Windows10)

    ‘MySQL’ is not recognized as an internal or external command,
    operable program or batch file.
    ‘MySQL’ is not recognized as an internal or external command,
    operable program or batch file.

    JBoss Bootstrap Environment

    JBOSS_HOME: C:\apps\dcm4chee-2.18.1-mysql

    JAVA: C:\Program Files\Java\jdk1.8.0_91\bin\java

    JAVA_OPTS: -Djava.library.path=”C:\apps\dcm4chee-2.18.1-mysql\bin\native” -server -Xms128m -Xmx512m -XX:MaxPermSize=128m -Djboss.messaging.ServerPeerID=0 -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000

    CLASSPATH: C:\Program Files\Java\jdk1.8.0_91\lib\tools.jar;C:\apps\dcm4chee-2.18.1-mysql\bin\run.jar

  4. Hi,

    It seems it does not find the mysql command. Could you edit the run.bat file and include the full pah to the mysql command?

  5. Hi Daniel,
    I am sorry that i need more help since m a newbie to programming.. how should i give path to mysql?

    This is the full run.bat file :
    @echo off
    rem ————————————————————————-
    rem JBoss Bootstrap Script for Win32
    rem ————————————————————————-

    rem $Id: run.bat 17856 2013-06-04 10:10:22Z javawilli $

    @if not “%ECHO%” == “” echo %ECHO%
    @if “%OS%” == “Windows_NT” setlocal

    set DIRNAME=.\
    if “%OS%” == “Windows_NT” set DIRNAME=%~dp0%
    set PROGNAME=run.bat
    if “%OS%” == “Windows_NT” set PROGNAME=%~nx0%

    pushd %DIRNAME%..
    set JBOSS_HOME=%CD%

    REM Add JBOSS_HOME/bin to the PATH
    set PATH=%JBOSS_HOME%\bin;%PATH%

    REM Add bin/native to the PATH if present
    if exist “%JBOSS_HOME%\bin\native” set PATH=%JBOSS_HOME%\bin\native;%PATH%
    if exist “%JBOSS_HOME%\bin\native” set JAVA_OPTS=%JAVA_OPTS% -Djava.library.path=”%JBOSS_HOME%\bin\native”

    rem Read all command line arguments

    REM The %ARGS% env variable commented out in favor of using %* to include
    REM all args in java command line. See bug #840239. [jpl]
    REM set ARGS=
    REM :loop
    REM if [%1] == [] goto endloop
    REM set ARGS=%ARGS% %1
    REM shift
    REM goto loop
    REM :endloop

    rem Find run.jar, or we can’t continue

    set RUNJAR=%JBOSS_HOME%\bin\run.jar
    if exist “%RUNJAR%” goto FOUND_RUN_JAR
    echo Could not locate %RUNJAR%. Please check that you are in the
    echo bin directory when running this script.
    goto END


    if not “%JAVA_HOME%” == “” goto ADD_TOOLS

    set JAVA=java

    echo JAVA_HOME is not set. Unexpected results may occur.
    echo Set JAVA_HOME to the directory of your local JDK to avoid this message.
    goto SKIP_TOOLS


    set JAVA=%JAVA_HOME%\bin\java

    rem A full JDK with toos.jar is not required anymore since jboss web packages
    rem the eclipse jdt compiler and javassist has its own internal compiler.
    if not exist “%JAVA_HOME%\lib\tools.jar” goto SKIP_TOOLS

    rem If exists, point to the JDK javac compiler in case the user wants to
    rem later override the eclipse jdt compiler for compiling JSP pages.
    set JAVAC_JAR=%JAVA_HOME%\lib\tools.jar


    rem If JBOSS_CLASSPATH or JAVAC_JAR is empty, don’t include it, as this will
    rem result in including the local directory in the classpath, which makes
    rem error tracking harder.
    if not “%JAVAC_JAR%” == “” set RUNJAR=%JAVAC_JAR%;%RUNJAR%


    rem Setup JBoss specific properties

    rem Add -server to the JVM options, if supported
    “%JAVA%” -version 2>&1 | findstr /I hotspot > nul
    if not errorlevel == 1 (set JAVA_OPTS=%JAVA_OPTS% -server)

    rem JVM memory allocation pool parameters. Modify as appropriate.
    set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:MaxPermSize=128m

    rem Specify the ID of the ServerPeer used by JBoss Messaging. Must be unique per JBoss instance
    set JAVA_OPTS=%JAVA_OPTS% -Djboss.messaging.ServerPeerID=0

    rem Use Compiling XSLT Processor (XSLTC)

    rem Uncomment to enable the jconsole agent locally
    rem Tell JBossAS to use the platform MBean server
    rem set JAVA_OPTS=%JAVA_OPTS% -Djboss.platform.mbeanserver
    rem Make the platform MBean server able to work with JBossAS MBeans
    rem set JAVA_OPTS=%JAVA_OPTS%

    rem Uncomment to enable the jconsole agent remotely on port 12345 with disabled security and ssl transport
    rem set JAVA_OPTS=%JAVA_OPTS%
    rem set JAVA_OPTS=%JAVA_OPTS%
    rem set JAVA_OPTS=%JAVA_OPTS%

    rem With Sun JVMs reduce the RMI GCs to once per hour
    set JAVA_OPTS=%JAVA_OPTS% -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000

    rem Set used in emitted audit log messages

    rem Set Node Name displayed in web login page
    rem (display hostname if dcm4che.archive.nodename isn’t set)
    rem set JAVA_OPTS=%JAVA_OPTS% -Ddcm4che.archive.nodename=DCM4CHEE

    rem JPDA options. Uncomment and modify as appropriate to enable remote debugging.
    rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%

    rem Setup the java endorsed dirs
    set JBOSS_ENDORSED_DIRS=%JBOSS_HOME%\lib\endorsed

    rem Enable remote access to jboss services and web interface
    if “%JBOSS_BIND_ADDR%” == “” set JBOSS_BIND_ADDR=

    rem Sample SSL debugging option:
    rem set JAVA_OPTS=%JAVA_OPTS%,handshake,data,trustmanager,help
    rem set JAVA_OPTS=%JAVA_OPTS%,handshake

    echo ===============================================================================
    echo JBoss Bootstrap Environment
    echo JAVA: %JAVA%
    echo ===============================================================================

    “%JAVA%” %JAVA_OPTS% “-Djava.endorsed.dirs=%JBOSS_ENDORSED_DIRS%” -classpath “%JBOSS_CLASSPATH%” org.jboss.Main -b %JBOSS_BIND_ADDR% %*

    if “%NOPAUSE%” == “” pause


  6. Hi
    I successfully installed dcm4chee and got login screen in webconsole and jmx console. I tried to upload a dicom file to dcm4chee using command :
    dcmsnd DCM4CHEE@localhost:11112 D:\dicom

    It gives error as :
    Scanning files to send
    Scanned 1 files in 0.034s (=34ms/file)
    11:40:13,756 INFO – Association(1) initiated Socket[addr=localhost/,port=11112,localport=55823]
    Connected to DCM4CHEE@localhost:11112 in 0.073s
    11:40:13,813 INFO – DCM4CHEE(1) <> 1:C-STORE-RSP[pcid=1, status=110H
    error=java.lang.RuntimeException: Failed to invoke ‘selectStorageFileS
    cuid=1.2.840.10008. Capture Image Storage
    ERROR: Received RSP with Status 0110H for D:\dicom\TG18-BR-1k-01.dcm, cuid=1.2.840.10008., tsuid=1.2.840.10008.1.2
    (0000,0002) UI #26 [1.2.840.10008.] Affected SOP Class UID
    (0000,0100) US #2 [32769] Command Field
    (0000,0120) US #2 [1] Message ID Being Responded To
    (0000,0800) US #2 [257] Command Data Set Type
    (0000,0900) US #2 [272] Status
    (0000,0902) LO #64 [java.lang.RuntimeException: Failed to invoke ‘selectStorageFileS] Error Comment
    (0000,1000) UI #54 [] Affected SOP Instance UI

    Sent 0 objects (=0.0KB) in 0.636s (=0.0KB/s)
    11:40:14,436 INFO – DCM4CHEE(1) <> A-RELEASE-RP
    Released connection to DCM4CHEE@localhost:11112
    11:40:14,441 INFO – DCM4CHEE(1): close Socket[addr=localhost/,port=11112,localport=55823]

    Please help in resolving this …

  7. Hi Dany , i have a DCMROUTER install OK this DCM have Weasys, ando Oviyam, but I need setup a second aetitle

    it`s Work fine whit the default Parameters Por 11112 Aetitle DCM4CHEE, now need configure a second Port and Aetitle

    Can you help me, to way a configure this feature?


    Samuel VL

  8. Hi,

    I got the below error after logged in, can you please help me to resolve this error

    Internal error

    Throwable: Can’t instantiate page using constructor public org.dcm4chee.web.war.MainPage()

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.