Docker

This guide will help you quickly set up digiRunner Open Source using the official Docker image from Docker Hub.

Prerequisites

Before installation, ensure your environment meets the following requirements:

Hardware

• Disk Space: At least 50 GB available (excluding OS)

Software

• Docker (We recommend Docker 22.0 or above )

Download: Docker Desktop

Run via Docker

To run digiRunner in a Docker container, copy and execute the command below in your terminal:

docker run -it -d --name digirunner -p 31080:18080 tpisoftwareopensource/digirunner-open-source

This command pulls the official image from Docker Hub and runs digiRunner in detached mode.

If you need other versions, you can go to the digiRunner official docker hub: https://hub.docker.com/r/tpisoftwareopensource/digirunner-open-source

Verification & Login

Check Container Status (Using command)

1. To check digiRunner in a Docker container, copy and execute the command below in your terminal:

docker logs -f digirunner

If you use another container name, please follow this rule to enter the command: docker logs -f <container_name>.

1. View the Logs tab and confirm digiRunner is running. Look for a message like:

2025-07-03 16:23:03 ...Started DgrApplication in 28.501 seconds (process running for 29.978)

First-Time Login

1. Open a browser and visit:

• Local: http://localhost:31080/dgrv4/login

• Remote: http://<your-host-ip>:31080/dgrv4/login

1. Use the default credentials:

• Username: manager

• Password: manager123

Security Tip: After logging in, immediately go to AC User Management > Users and update your password. (See SMTP settings and user update instructions for more details.)

Advanced property settings

This is how to customize digiRunner behavior using environment variables in a docker run command. These settings allow you to control CORS headers, instance identity, and data persistence.

General Syntax

docker run -it -d
-e KEY1="VALUE1"
-e KEY2="VALUE2"
-v <host_path>:<container_path>
-p <host_port>:<container_port>
tpisoftwareopensource/digirunner-open-source

• The command always starts with docker run.

• The image name tpisoftwareopensource/digirunner-open-source must always be at the end.

• The order of -e, -v, and -p options can vary, but each section must be complete and correctly formatted.

CORS Header Configuration

To configure allowed HTTP headers for CORS:

docker run -it -d \
   -e CORS_ALLOW_HEADERS="Content-Type, Authorization, SignCode, Language, OTHER_CUSTOM_HEADER" \
   -p 31080:18080 \
   tpisoftwareopensource/digirunner-open-source

• Override the value of cors.allow.headers in the applicaiton.properties file.

• Property names in Java config are converted:

  • All lowercase with dots (cors.allow.headers) → ALL_CAPS with underscores (CORS_ALLOW_HEADERS)

Setting Instance ID

docker run -it -d \
   -e DIGI_INSTANCE_ID="OSPO" \
   -p 31080:18080 \
   tpisoftwareopensource/digirunner-open-source

• Sets the digi.instance.id property.

• Useful for identifying different instances (e.g., staging, dev, production).

Persistent Database Setup (H2 File Mode)

First-Time Initialization

docker run -it -d \
   -e SPRING_DATASOURCE_URL="jdbc:h2:file:/opt/db/digirunner;DB_CLOSE_DELAY=-1;NON_KEYWORDS=VALUE;Mode=MySQL" \
   -v ./dgrdb:/opt/db \
   -p 31080:18080 \
   tpisoftwareopensource/digirunner-open-source

• Stores H2 database in ./dgrdb on the host machine.

• Initializes the schema automatically on first run.

Subsequent Runs

docker run -it -d \
   -e SPRING_DATASOURCE_URL="jdbc:h2:file:/opt/db/digirunner;DB_CLOSE_DELAY=-1;NON_KEYWORDS=VALUE;Mode=MySQL" \
   -e SPRING_SQL_INIT_MODE="never" \
   -v ./dgrdb:/opt/db \
   -p 31080:18080 \
   tpisoftwareopensource/digirunner-open-source

• Prevents re-initialization of the database on subsequent launches

• Ensures previously stored data remains intact

Other support

Still need help? Visit our GitHub repository and post your issue in the Discussions or Issues section. Our team will respond promptly.

You are now ready to run digiRunner via Docker!