Installation Guide

This guide provides step-by-step instructions for installing and configuring the DSClient application.

Alternative installation methods

The recommended installation pathway is to use a Docker container.
For other solutions, please reach out to the Chemaxon Professional Services team for further assistance.

---

Version Compatibility

CompReg/DSClient Version	Supported Java Versions
23.9.x	>= 11
24.3.x	>= 17
25.1.x	>= 17

Upcoming Java Upgrade

Version 25.3.0 is the last version of the DSClient which will support Java 17. The next releases will require at least Java 21.

---

Video Walkthrough

Prerequisites

The following items are required before installing the Chemaxon DSClient:

- A configured Chemaxon CompReg instance with access to an admin account and the command-line interface
- Docker installed and running with access to Chemaxon Docker registry - chemaxon.jfrog.io
- PostgreSQL or Oracle database for downstream storage
- A valid Chemaxon license for CompReg and DSClient

System Requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
Memory	4 GB	8+ GB
Disk Space	10 GB	50+ GB

---

Installation Steps

Step 1: Configure CompReg

New CompReg InstallUpdate CompReg

Authentication

Access to the Chemaxon Docker registry requires authentication:

1. Pull and deploy a fully-functional CompReg system in Docker with the following compreg.env file

docker login chemaxon.jfrog.io
docker network create compreg-net

docker run -d --name compreg-db \
--network compreg-net \
-p 5433:5432 \
-v compreg-db-data:/var/lib/postgresql/data \
-e POSTGRES_DB=regsys \
-e POSTGRES_USER=regsys \
-e POSTGRES_PASSWORD=OnlineDemo2 \
postgres:15

docker run -d --name compregDemo \
--network compreg-net \
--env-file compreg.env \
-p 8080:8080 \
chemaxon.jfrog.io/cxn-docker-release/registration:25.2.4-2602171141

HTTPActiveMQ

compreg.env

# Database Configuration
RegDBType=PostgreSQL
RegDBDriver=org.postgresql.Driver
RegDBUrl=jdbc:postgresql://compreg-db:5432/reg
RegDBUser=regsys
RegDBPass=OnlineDemo
RegDBMaxActive=30
RegDBValidationQuery=SELECT 1

# Downstream Publishing
RegDownstreamMode=Database
RegDownstreamPublishEnabled=true
RegDownstreamFusedImageFormat=mol:V3

compreg.env

# Database Configuration
RegDBType=PostgreSQL
RegDBDriver=org.postgresql.Driver
RegDBUrl=jdbc:postgresql://compreg-db:5432/reg
RegDBUser=regsys
RegDBPass=OnlineDemo
RegDBMaxActive=30
RegDBValidationQuery=SELECT 1

# Downstream Publishing via ActiveMQ
RegDownstreamMode=ActiveMQ
RegDownstreamPublishEnabled=true
RegDownstreamFusedImageFormat=mol:V3
RegDownstreamJmsPersistent=true
RegDownstreamJmsBrokerURL=tcp://activemq:61616
RegDownstreamJmsDestinationName=REGISTRATION.DS

ActiveMQ (JMS) Message Broker

An ActiveMQ broker is required for JMS messaging and an example ActiveMQ broker can be run using Docker on the same Docker network as the CompReg/DSClient with the following settings:

• Port 61616 — OpenWire protocol (JMS communication between CompReg, DSClient, and the broker)
• Port 8161 — Web management console (http://localhost:8161, default credentials: admin / admin)

  docker run -d --name activemq \
  --network compreg-net \
  -p 61616:61616 \
  -p 8161:8161 \
  -v ./activemq.xml:/opt/apache-activemq/conf/activemq.xml \
  apache/activemq-classic:latest

activemq.xml

...
<destinations>
  <queue physicalName="REGISTRATION.DS"/>
</destinations>

In this example, RegDownstreamJmsBrokerURL refers to container's IP address.
A full activemq.xml configuration is available here

2. Finalize the installation using the built-in wizard running on the docker instance http://{compregDemo external IP}:8080

HTTPActiveMQ

1. Modify the CompReg environment configuration to include:
   
   compreg.env

   # Downstream Publishing
   RegDownstreamMode=Database
   RegDownstreamPublishEnabled=true
   RegDownstreamFusedImageFormat=mol:V3
   

2. Restart the CompReg instance

1. Modify the CompReg environment configuration to include:
   
   compreg.env

   # Downstream Publishing via ActiveMQ
   RegDownstreamMode=ActiveMQ
   RegDownstreamPublishEnabled=true
   RegDownstreamFusedImageFormat=mol:V3
   RegDownstreamJmsPersistent=true
   RegDownstreamJmsBrokerURL=tcp://{ActiveMQ Broker IP}:61616
   RegDownstreamJmsDestinationName=REGISTRATION.DS
   

2. Restart the CompReg instance

---

Step 2: Create Client Credentials in CompReg

1. Create DSClient User in CompReg

1. Access CompReg web UI at `http://{compregDemo external IP}:8080`
2. Navigate to **Administration** → **Users**
3. Create a new user — `DSUser`
4. Assign role in Groups: `REGISTRY_ADMINISTRATOR` or `SUPER`

1. Connect to the CompReg container and create authentication credentials:

# Connect to CompReg container
docker exec -it compregDemo bash

# Create client secret
/home/cxnapp/install/RegistryCxn/bin/RegistryCxn add-secret \
  -client DSClient \
  -secret YourClientSecret

!!! info "Authentication"
    This configuration ensures that the DSClient will work with all popular authentication types supported by CompReg.
    This data is stored in the ``clients`` table in CompReg database.

---

Step 3: Prepare Downstream Database

Create the downstream database schema to be used with the DSClient.
DSClient will automatically create the required tables on first startup.

PostgreSQLOracleSQLite

Testing

A docker-based Postgres server with suitable preconfigured ds database can be created for testing using

docker run -d --name dsclient-db  \
--network compreg-net \
-p 5432:5432 \
-v downstream-db-data:/var/lib/postgresql/data \
-e POSTGRES_DB=ds \
-e POSTGRES_USER=DSDBUser \
-e POSTGRES_PASSWORD=YourDSDBPassword \
postgres:15

-- Connect as superuser
CREATE DATABASE ds;
CREATE USER dsdbuser WITH PASSWORD 'YourDSDBPassword';
GRANT ALL PRIVILEGES ON DATABASE ds TO dsdbuser;

-- Connect as DBA
CREATE USER dsdbuser IDENTIFIED BY YourDSDBPassword;
GRANT CONNECT, RESOURCE TO dsdbuser;
GRANT UNLIMITED TABLESPACE TO dsdbuser;

SQLite is a file-based database that requires no server setup. Ensure the target directory exists and is writable:

# Create the data directory
mkdir -p /var/data

# Set appropriate permissions
chmod 755 /var/data

Persistent data

A volume must be mounted in Docker in order for the SQLite database to be persistent.

---

Step 4: Configure DSClient

Create the dsclient.env configuration file for the DSClient.

Supported Databases Configuration Options

PostgreSQLOracleSQLite

dsclient.env

# DSClient Home
REGISTRYCXN_DSCLIENT_HOME=/usr/local/tomcat

# Downstream Database Configuration
RegDSDBType=PostgreSQL
RegDSDBDriver=org.postgresql.Driver
RegDSDBUrl=jdbc:postgresql://dsclient-db:5432/ds
RegDSDBUser=DSDBUser
RegDSDBPass=YourDSDBPassword
RegDSDBMaxActive=30
RegDSDBValidationQuery=SELECT 1

dsclient.env

# DSClient Home
REGISTRYCXN_DSCLIENT_HOME=/usr/local/tomcat

# Downstream Database Configuration
RegDSDBType=Oracle
RegDSDBDriver=oracle.jdbc.OracleDriver
RegDSDBUrl=jdbc:oracle:thin:@//dsclient-db:1521/ORCL
RegDSDBUser=DSDBUser
RegDSDBPass=YourDSDBPassword
RegDSDBMaxActive=30
RegDSDBValidationQuery=SELECT 1 FROM DUAL

dsclient.env

# DSClient Home
REGISTRYCXN_DSCLIENT_HOME=/usr/local/tomcat

# Downstream Database Configuration
RegDSDBType=SQLite
RegDSDBDriver=org.sqlite.JDBC
RegDSDBUrl=jdbc:sqlite:/var/data/downstream.db
RegDSDBUser=
RegDSDBPass=
RegDSDBMaxActive=1
RegDSDBValidationQuery=SELECT 1

Communication Type Options

HTTP Polling (Recommended)ActiveMQ (JMS)

HTTP polling is the recommended communication method for new installations.

dsclient.env

RegDSClientCommunicationType=HTTP
RegDsClientHttpCompregHost=http://compregDemo:8080
RegDsClientHttpCompregClientId=DSClient
RegDsClientHttpCompregClientSecret=YourClientSecret
RegDsClientHttpCompregUser=DSUser
RegDsClientHttpPaginationLimit=100
RegDsClientHttpPollingFrequencySeconds=10

ActiveMQ can be used for push-based message delivery.

RegDSClientCommunicationType=QUEUE
RegDsClientJmsBrokerUrl=tcp://activemq:61616
RegDsClientJmsDestinationName=REGISTRATION.DS

---

Step 5: Start DSClient

docker run -d \
  --name dsclient \
  --network compreg-net \
  --env-file dsclient.env \
  chemaxon.jfrog.io/cxn-professional-services-docker-release/registration_dsclient:25.3.0-202511070832

---

Step 6: Verify Installation

Check the DSClient logs for successful startup:

docker logs -f dsclient

Expected Output

You should see one of the following messages:

• No message to process - DSClient is running but no new registrations
• Successfully finished job - DSClient successfully processed messages

---

Docker Compose Example

For a complete deployment, use Docker Compose:

docker-compose.yml

version: '3.8'

services:
  compreg-db:
    image: postgres:15
    environment:
      POSTGRES_DB: reg
      POSTGRES_USER: regsys
      POSTGRES_PASSWORD: RegDBPassword
    volumes:
      - compreg-data:/var/lib/postgresql/data

  downstream-db:
    image: postgres:15
    environment:
      POSTGRES_DB: ds
      POSTGRES_USER: dsdbuser
      POSTGRES_PASSWORD: DSDBPassword
    volumes:
      - downstream-data:/var/lib/postgresql/data

  compreg:
    image: chemaxon.jfrog.io/cxn-docker-release/registration:25.3.1-2511111222

    depends_on:
      - compreg-db
    environment:
      RegDBType: PostgreSQL
      RegDBDriver: org.postgresql.Driver
      RegDBUrl: jdbc:postgresql://compreg-db:5432/reg
      RegDBUser: regsys
      RegDBPass: RegDBPassword
      RegDBMaxActive: 30
      RegDBValidationQuery: SELECT 1
      RegDownstreamMode: Database
      RegDownstreamPublishEnabled: "true"
      RegDownstreamFusedImageFormat: mol:V3
      CHEMAXON_LICENSE_URL: http://license-server/license.cxl
    ports:
      - "8080:8080"

  dsclient:
    image: chemaxon.jfrog.io/cxn-professional-services-docker-release/registration_dsclient:25.3.0-202511070832
    depends_on:
      - compreg
      - downstream-db
    environment:
      REGISTRYCXN_DSCLIENT_HOME: /usr/local/tomcat
      RegDSDBType: PostgreSQL
      RegDSDBDriver: org.postgresql.Driver
      RegDSDBUrl: jdbc:postgresql://downstream-db:5432/ds
      RegDSDBUser: dsdbuser
      RegDSDBPass: DSDBPassword
      RegDSDBMaxActive: 30
      RegDSDBValidationQuery: SELECT 1
      RegDSClientCommunicationType: HTTP
      RegDsClientHttpCompregHost: http://compreg:8080
      RegDsClientHttpCompregClientId: DSClient
      RegDsClientHttpCompregClientSecret: YourClientSecret
      RegDsClientHttpCompregUser: DSUser
      RegDsClientHttpPaginationLimit: 100
      RegDsClientHttpPollingFrequencySeconds: 10

volumes:
  compreg-data:
  downstream-data:

Start all services:

docker-compose up -d