cdiscdocker/cdisc-rules-engine repository overview

⁠CDISC Rules Engine Docker Image

This Docker image contains the CDISC Rules Engine, a tool for validating clinical trial data against CDISC standards. The container uses the most recent release of CORE engine per the CDISC Core Engine repository. To learn more, visit our GitHub repository or the official CDISC website:
CDISC Rules Engine GitHub⁠
CDISC Website⁠

⁠Quick Start

⁠Pull the Image

To pull the image from Docker Hub:

docker pull cdiscdocker/cdisc-rules-engine:latest

⁠Basic Usage

The general format for running validations is:

docker run --rm -it \
  -v /path/to/local/output:/data/output \
  -v /path/to/local/datasets:/data/input \
  cdiscdocker/cdisc-rules-engine /app/core validate -s <standard> -v <version> -d /data/input -o /data/output/name_of_report

This mounts two volumes to the container--one with your datasets and one where the report will go. These links between your local filesystem and the container allow for the datasets to be accessed in the container and for the report to go to your local computer when generated. Replace /path/to/local/output and /path/to/local/datasets with your actual paths. the :/data/output and :/data/input should be present after these paths. name_of_report should also be replaced in the output command.

⁠Windows (PowerShell) Example:

docker run --rm -it `
  -v "C:\path\to\output:/data/output" `
  -v "C:\path\to\datasets:/data/input" `
  cdiscdocker/cdisc-rules-engine /app/core validate -s sdtmig -v 3-4 -d /data/input -o /data/output/report

⁠Linux/Mac Example:

docker run --rm -it \
  -v "$(pwd):/data/output" \
  -v "/path/to/datasets:/data/input" \
  cdiscdocker/cdisc-rules-engine /app/core validate -s sdtmig -v 3-4 -d /data/input -o /data/output/report

note--this example uses $(pwd) which can be used in either windows, linux, or mac to use the directory you are currently in to output the reports to.

⁠Parameters Explained

• -s <standard>: Specify the CDISC standard (e.g., sdtmig, adamig)
• -v <version>: Version of the standard (e.g., 3-4)
• -d /data/input: Directory containing input datasets (mounted from your local machine)
• -o /data/output/report: Output file for the validation report

⁠Additional Commands

To see all available commands:

docker run --rm cdiscdocker/cdisc-rules-engine /app/core --help

To see all command options:

docker run --rm cdiscdocker/cdisc-rules-engine /app/core COMMAND --help

⁠Notes

• The container runs as root by default. If you encounter permission issues, you may need to adjust the ownership of the output directory.
• To run update-cache command, you will need to give the container your cdisc library API key. this can be performed in two ways:

1. Setting a local environmental variable then giving it to the container on run UNIX

export CDISC_API_KEY="your_api_key_here"
docker run --rm -e CDISC_LIBRARY_API_KEY=$CDISC_API_KEY cdiscdocker/cdisc-rules-engine /app/core COMMAND --help

Windows Powershell

$env:CDISC_LIBRARY_API_KEY="your_api_key_here"
docker run --rm -e CDISC_LIBRARY_API_KEY=$CDISC_API_KEY cdiscdocker/cdisc-rules-engine /app/core COMMAND --help 

you do not need the -e command, you can instead just run directly using the powershell environmental variable

docker run cdiscdocker/cdisc-rules-engine /app/core update-cache --apikey $env:CDISC_LIBRARY_API_KEY

1. Using docker secret, which requires swarm mode to access but ensures key encryption and limits exposure risk.

docker swarm init

UNIX

export CDISC_LIBRARY_API_KEY="your_actual_api_key_here" 
echo $CDISC_LIBRARY_API_KEY | docker secret create cdisc_api_key - 
docker service create \
    --name cdisc-rules-engine \
    --secret cdisc_api_key \
    --mount type=bind,source=path_to/output/directory,target=/data/output \
    --mount type=bind,source=path/to/your/data/files,target=/data/input \
    --replicas 1 \
    --restart-condition none \
    cdiscdocker/cdisc-rules-engine
docker service logs -f cdisc-rules-engine

path/to/your/data/files and path_to/output/directory must be replaced with your file paths

Windows Powershell

$env:CDISC_LIBRARY_API_KEY = "your_actual_api_key_here"
echo $env:CDISC_LIBRARY_API_KEY | docker secret create cdisc_api_key -
docker service create `
    --name cdisc-rules-engine `
    --secret cdisc_api_key `
    --mount type=bind,source=path/to/your/data/files,target=/data/input `
    --mount type=bind,source=path_to/output/directory,target=/data/output `
    --replicas 1 `
    --restart-condition none `
    cdiscdocker/cdisc-rules-engine

⁠Troubleshooting:

Some macOS users, particularly those on M1 Macs, may encounter the following error when using a relative path for input data in Docker:

The path /path/to/data is not shared from the host and is not known to Docker.
You can configure shared paths from Docker -> Preferences... -> Resources -> File Sharing.
See https://docs.docker.com/desktop/settings/mac/#file-sharing for more info

This issue occurs because Docker for macOS does not recognize the relative paths for shared directories by default. The directories used in Docker containers need to be explicitly shared from the host system. Solution To resolve this issue, use the absolute path to the dataset files instead of relative paths. Your command will look like this

docker run --rm -it \
  -v "$(pwd):/data/output" \
  -v "/full/absolute/path/to/datasets:/data/input" \
  cdiscdocker/cdisc-rules-engine /app/core validate -s sdtmig -v 3-4 -d /data/input -o /data/output/report

⁠Issue Reporting:

Should you have issues or concerns regarding our docker implementation, please visit our github and create a ticket with [Docker] in the title. We will look into the issue as soon as possible.

⁠Note:

The example commands provided in this documentation are intended for testing and demonstration purposes within a command-line interface (CLI) environment. They are not meant for production implementations.

While the CDISC Rules Engine CLI is fully functional within the Docker container:

• Users are solely responsible for implementing this tool in production systems.
• Commands and Configurations may require adaptation to meet specific infrastructure, security, or compliance requirements.
• Always test configurations in non-production environments before deployment.
• Consult your IT/DevOps teams for production solutions.