Docker compose

digiRunner | Quick Deployment Guide with Docker Compose

This guide will walk you through the steps of deploying the open-source version of digiRunner using Docker Compose.

Prerequisites

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

Hardware Requirements

• CPU: 2 cores or higher

• RAM: 4 GB or more

• Disk Space: Recommended at least 50 GB available (excluding the OS)

Software Requirements

• Required Software:

  • Docker (container runtime)

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

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

Deploy & Start with Docker Compose

After downloading the configuration file manually, you can start digiRunner. You may preview or modify the config file as needed.

1. Download

Download the file from the link below and save it to your computer.

[Download Link]

1. Start the Services

Open your terminal and navigate (cd) to the directory containing the docker-compose.yml file, then run:

docker compose up -d

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

Verification & Login

After deployment, follow these steps to verify the services and log in to the admin console.

Check Container Status

Run the command below in the same directory as your file:

docker compose ps

Make sure the digirunner-open-source-dgr-1 container shows a Start time in the STATUS field.

First-Time Login to Admin Console

1. Open a browser and go to:

• http://localhost: 31080/dgrv4/login (if running locally)

• http://<your-host-ip>:31080/dgrv4/login (if running on a remote server)

1. Default admin credentials:

• Username: manager

• 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, immediately go to AC User Management > Users to change your password. (For details, please refer to SMTP Configuration and Update users).

Management & Maintenance

• 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. This means data (including API configs, user accounts, etc.) 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.

1. Create a File

Manually create a docker-compose.yaml(Please use the same name) file in your preferred project directory.

1. Paste the Following Content

Paste the content below 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 : This maps your localdbfolder (same level asdocker-compose.yaml`) to the path where digiRunner stores its database. All changes are saved in real-time.

• Smart Initialization : This pre-service checks if a db file already exists.

  • On first startup (empty db folder), it triggers database creation.

  • On subsequent restarts (existing .db file), it prevents reinitialization and protects existing data.

1. Start the Services

In your terminal, navigate to the folder containing docker-compose.yaml and run:

docker compose up -d

After running, you’ll see a db folder containing dgrdb.mv.db — this is your persistent database file.

Troubleshooting

Basic Troubleshooting Steps

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

1. Check Container Status

Run the following:

docker compose top

Explanation: Lists all containers (including stopped ones). Check the STATUS field for the tpi-digirunner container. It should be Up. If it’s Exited, there’s a startup failure.

1. View Logs

If the container is Up but not functioning properly, check logs for errors:

docker compose logs -f

This streams live logs and shows application-level issues.

1. Restart Container

If the container is unresponsive or needs a reset:

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 & Reinstall

If the container crashes and logs show critical errors, back up important files (e.g., config, DB), delete the faulty containers, and rerun the setup.