Docker compose

digiRunner | Quick Deployment Guide with Docker Compose

This section walks you through deploying the open-source version of digiRunner using Docker Compose.

Prerequisites

Before starting the installation, ensure your host environment meets the following requirements:

Hardware Requirements

• CPU: 2 cores or higher

• RAM: 4 GB or more

• Disk Space: 50 GB or more (excluding the OS)

Software Requirements

• Docker - container runtime

• Docker Compose - tool to define and run multi-container Docker applications

Official download: https://www.docker.com/products/docker-desktop/

Starting digiRunner with Docker Compose

Download the configuration file, start digiRunner, and preview or modify the file as needed.

Download

Download the Docker Compose YAML file and save it to your computer.

Start the Services

1. Open a terminal and navigate (cd) to the directory containing the docker-compose.yml file.

2. Run the following command:

docker compose up -d

This command will read the docker-compose.yml in the current directory and start all services in the background.

Verification and Login

After deploying digiRunner, verify that all services are running and log in to the admin console.

Check Container Status

1. Run the following command in the directory containing the docker-compose.yml file:

docker compose ps

1. Make sure the digirunner-open-source-dgr-1 container shows Up (with running time) in the STATUS field.

First-Time Login to Admin Console

1. Open a browser and navigate to one of the following URLs:

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

   • On a remote server: http://<your-host-ip>:31080/dgrv4/login

2. Log in using the default admin credentials:

   • Username: manager

   • User password: manager123

1. Upon successful login, you will see the text digiRunner Community displayed in the upper left corner.

Security Tip: After your first login, go to AC User Management > Users and change your password immediately. For details, please refer to SMTP Configuration and Update users.

Management and Maintenance

Use the following commands to manage and maintain digiRunner services.

• View logs:

docker compose logs -f

• Stop services:

docker compose down

• Restart services:

docker compose up -d

Advanced Configuration: H2 Database Persistence (Important)

By default, the open-source version uses an in-memory H2 database. Consequently, all data, including API configurations and user accounts, will be lost when the container stops or restarts.

To retain data permanently (known as “persistence”), follow the steps below to store the database files on your host machine.

Create a File

Manually create a file named docker-compose.yaml in your preferred project directory.

Add YAML Configuration

Paste the following content into your newly created file:

name: digirunner-open-source

services:
  dgr-h2db-detect:
    container_name: dgr-h2db-detect
    image: bash
    volumes:
      - ./db:/opt/db
      - shared:/opt/shared
    command: |
      bash -c '
      cat << EOF > /opt/shared/dgr.args
      -Xms2g
      -Xmx4g
      -DdigiRunner.token.key-store.path=/opt/digirunner/keys
      -Dserver.port=18080
      -Dspring.datasource.url=jdbc:h2:/opt/digirunner/db/dgrdb;NON_KEYWORDS=VALUE;Mode=MySQL
      EOF
      ls /opt/db/*.db &> /dev/null && echo "-Dspring.sql.init.mode=never" >> /opt/shared/dgr.args || echo "-Dspring.sql.init.mode=always" >> /opt/shared/dgr.args;
      cat /opt/shared/dgr.args
      '

  dgr:
    image: tpisoftwareopensource/digirunner-open-source
    container_name: dgr-gateway
    depends_on:
      dgr-h2db-detect:
        condition: service_completed_successfully
    ports:
      - "31080:18080"
    environment:
      - TZ=Asia/Taipei
    command:
      - "@/opt/shared/dgr.args"
      - "org.springframework.boot.loader.launch.PropertiesLauncher"
    volumes:
      - ./db:/opt/digirunner/db
      - shared:/opt/shared

volumes:
  shared:

Explanation of Configuration

• Data Persistence : Maps your local db folder to digiRunner’s database path. All changes are saved in real time. Place the folder at the same directory level as docker-compose.yml.

• Smart Initialization : Checks whether a .db file exists.

  • On first startup, with an empty db folder, it triggers database creation.

  • On subsequent restarts, with an existing .db file, it prevents reinitialization and preserves the existing data.

Start the Services

1. Open a terminal, and navigate to the directory containing the docker-compose.yml file.

2. Run the following command:

docker compose up -d

After the command completes, a db folder will be created containing dgrdb.mv.db, which is your persistent database file.

Troubleshooting

Basic Troubleshooting Steps

If you encounter issues after installing digiRunner, follow these steps:

Step 1. Check Container Status

1. Run the following command to list all containers, including stopped ones:

docker compose top

1. Check the STATUS field for the tpi-digirunner container. It should display Up. If it shows Exited, a startup failure has occurred.

Step 2. View Logs

If the container is Up but not functioning properly, run the following command to stream real-time logs and identify application-level issues:

docker compose logs -f

Step 3. Restart Container

If the container is unresponsive or needs a reset, run the following commands to restart it:

docker compose down

docker compose up -d

After restarting, repeat Steps 1 and 2 to verify functionality.

Common Issues to Check

• Is Docker installed?

  • Run docker info to confirm.

• Is Docker Compose installed?

  • Run docker compose version to confirm.

Backup and Reinstall

If the container continues to crash or logs show critical errors, back up important files, such as config and the database file, delete the faulty containers, and rerun the setup.