Using Dundas BI Docker containers

1. Overview

Deploying Dundas BI using Docker containers allows you to run on the OS or cloud platform of your choice, isolates Dundas BI from other apps and your server's operating system, and allows you to manage the container resources. These Docker images are also the basis for Kubernetes deployment, which adds automatic scaling and high availability options and a more automated deployment configuration.

This article details the steps to run Dundas BI Docker images as containers using Docker directly, including setting up Dundas BI application and warehouse databases, and configuration options.

2. Dundas BI Docker Hub images

The Dundas BI Docker images are located in the Docker Hub under the Dundas organization. The following table lists the different Dundas BI repository images:

They are built off of the .NET Core Docker images. Versions 9 and earlier use the 3.1-bionic tag for the Ubuntu 18.04 operating system, and later versions use 6.0-focal for Ubuntu 20.04.

2.1. Tags

As listed in the Tags tab for the images above, there are tags available for different published version numbers, or latest (the default) for the latest version. In addition:

• In version 23.2 and up, the website image is separate by default from the export and Python functionality provided in separate images. These need to be set up to run together with the website and then be configured in Dundas BI. To include export and Python functionality together with the website in the same image instead, use the tags containing -original in the name for the website image.
• You can optionally choose an image tag ending with -slim to exclude certain features if unneeded such as Python, the metric set Assistant, ODBC, JDBC, and IBM Db2. Support for exporting content is also excluded from the -slim image but included in -slim-export.

Many examples on this page specify :latest as the tag following the image name. Change this if needed to your desired tag.

3. Dundas BI application and warehouse databases

Dundas BI runs using Microsoft SQL Server/Azure SQL or PostgreSQL databases for its own application and warehouse data storage. These databases need to be created before most Dundas BI images can be used.

To create or upgrade application and warehouse databases using Docker, run the setup image using a command like the following, replacing {version} with the version or tag you would like to set up:

docker run -it --rm dundas/dundas-bi-setup:{version}

This will start the Dundas BI Deployment wizard, similar to the one used when deploying Dundas BI directly on Linux but only with options used for container deployments. Choose the option to create databases, or if you have existing databases from a previous version you can choose the option to upgrade them.

A Microsoft or PostgreSQL database server will need to be running and accessible to the setup container before it can create the databases. You will be asked for the database server name or address and the credentials of an account with sufficient permissions.

In the last step of the wizard before the databases are created, the connection strings used for each database are displayed. You can copy the application database connection string to use for reference for starting other Dundas BI images (asterisks in the password field would need to be replaced with a valid password).

3.1. Unattended handling of databases

In version 8.0.1 and up, an alternative to using the wizard is to use the --handledatabase option when running the setup image. This feature is designed as follows:

• If the connection string passed is to a database that doesn't exist, one will be created and initialized. The warehouse will also be created by appending " Warehouse" to the application database name.
• If the database exists but is not up to date, the database will be upgraded.
• If the database exists and is up to date, no tasks will run and success will be returned.

Below are the arguments that can be passed to the handle database option:

The following is an example of how the handle database option can be used:

docker run -it -e DUNDAS_BI_SETUP_ORCHESTRATOR_URL="" --rm  dundas/dundas-bi-setup:latest --handledatabase --DUNDAS_BI_APP_DB_CONN_STRING "Data Source=192.168.0.184; Initial Catalog=Dundas BI MyInstance; User Id=DundasBIUser; Password=SomePassword" --DUNDAS_BI_ADMIN_PASSWORD "1234"

Similarly, rather than using the wizard, you can add Dundas-provided samples to an instance using the --addsample command with Dundas BI versions 11 and higher, followed by the following argument:

For example:

docker run -it --rm dundas/dundas-bi-setup:latest --addsample --DUNDAS_BI_SAMPLE_NAME Performance  --DUNDAS_BI_APP_STORAGE SqlServer --DUNDAS_BI_APP_DB_CONN_STRING "Data Source=xxxx;User Id=xxxx; Password=xxxx;Initial Catalog=xxxx"

4. Running Dundas BI images

The images used to run the Dundas BI application rely on the application database created and prepared earlier, and the first thing they need to know is how to connect to it via a connection string. There are two different ways to specify the connection string: either by setting environment variables, or using a mounted volume that places a dbi.config file.

Connection strings were generated and displayed by the wizard if you used the setup image, and specified in the dbi.config file if you have an existing Dundas BI instance that was installed directly on Windows or Linux. You can also see Dundas BI config file for more details and examples.

4.1. Environment variables

You can specify the application database connection using Docker environment variables. These are typically set in one of the following ways:

• Compose file
• Shell environment variables
• Environment file
• Dockerfile

For more information see: Environment variables in Compose.

In order to start a Dundas BI Docker container (other than the setup image) you should set two environment variables:

4.2. Mapped dbi.config file

An alternative to using environment variables is to map/mount an un-encrypted dbi.config file to the container to the following location:

/usr/share/dundas/bi/Files/Container/www/BIWebsite/App_Data/dbi.config

See the Dundas BI config file article for details on this config file.

The examples section below includes one that maps a dbi.config file. For more information about mounting a file using volumes, see Use volumes in the Docker documentation.

4.3. Dundas BI website port

The dundas/dundas-bi-website uses port 8080, so published ports should map to this when using published ports. The examples section below demonstrates this.

4.4. Application URL settings

Some configuration settings in Dundas BI need to be set for certain functionality to work correctly. The Internal Application URL and External Application URL settings can be set within the Dundas BI application itself in its configuration settings, during setup using --handledatabase, or you can set them as environment variables if preferred.

• The scheduler service uses the set Internal Application URL to access the Dundas BI website, which runs on port 8080. When these run in separate containers, Docker networking determines how these can access each other. host.docker.internal or an equivalent can refer to a published port from the host (e.g., http://host.docker.internal/ for port 80), the default bridge network allows containers to connect directly only via IP address, while a user-defined bridge network allows you to refer to containers by their assigned names (e.g., http://dundaswebsite:8080/ after using docker run --net dundas-net --name dundaswebsite ... for the website image). You can also use Compose networking. When using a single container (dundas-bi-full image) or with host networking, the scheduler service could access http://localhost:8080/.
• The External Application URL should be the URL users will use to access the root level of the Dundas BI website. For example, if you are publishing to port 80, this might be http://yourservername/ within your local network.

In newer versions of Dundas BI, there are separate images by default for export and Python functionality. The data cube storage image can optionally also run separately. These need to be set up to run using Docker Compose or similar, as shown below for the authbridge container. The subpaths used in their URLs are up to you but the URLs then need to be set in the corresponding URL configuration setting, e.g., Export Microservice URL, Python Microservice URL, Data Storage Microservice URL.

If you prefer to set the URLs used by the scheduler service using environment variables rather than in Dundas BI's administration UI, the following set these URLs on the global scope before the application starts:

4.5. Examples

The following command can be executed to start the Dundas BI website with environment variables and publishing to port 80:

docker run -it -p:80:8080 \
-e DUNDAS_BI_APP_DB_CONN_STRING="Data Source=host.docker.internal;User Id=dbiuser;Password=pw;Initial Catalog=Dundas BI DockerTest" \
-e DUNDAS_BI_APP_STORAGE="SqlServer" \
dundas/dundas-bi-website:latest

The following command can be executed to start the Dundas BI scheduler with environment variables:

docker run -it \
-e DUNDAS_BI_APP_DB_CONN_STRING="Data Source=host.docker.internal;User Id=dbiuser;Password=pw;Initial Catalog=Dundas BI DockerTest" \
-e DUNDAS_BI_APP_STORAGE="SqlServer" \
dundas/dundas-bi-scheduler:latest

The following command can be executed to run the dt health check with environment variables (using a Postgres database as an example):

docker run -it \
-e DUNDAS_BI_APP_DB_CONN_STRING="Host=host.docker.internal;Port=5432;Database="Dundas BI DockerTest";User ID=dbiuser;Password=pw;" \
-e DUNDAS_BI_APP_STORAGE="Postgres" \
dundas/dundas-bi-dt:latest healthcheck

The following command can be executed to start the Dundas BI website with a mounted dbi.config file using a local file (/dbi.config):

docker run -it -p:80:8080 \
-v /dbi.config:/usr/share/dundas/bi/Files/Container/www/BIWebsite/App_Data/dbi.config \
dundas/dundas-bi-website:latest

4.6. Restart policy

You should set a restart policy when Dundas BI is in use and meant to be running continuously for multiple users to access. In Dundas BI version 10 and higher, the website and other services will respect the restart policy and only restart according to the setting, including if a service stops for an expected reason such as when loading newly added extensions.

If you are using docker run commands like those above, you can add an argument, e.g., docker run --restart=always... You can also specify the policy in a compose file.

5. Kestrel and NGINX

The dundas/dundas-bi-website container uses a Kestrel web server. Another service like NGINX, IIS or Apache should be used if you require more options like SSL. For more information regarding Kestrel web server and reverse proxies, see Dundas BI and reverse proxies, and see Kestrel web server implementation in ASP.NET Core in Microsoft's documentation.

5.1. Using NGINX service as reverse proxy with Docker Compose

The following Docker Compose example contains two files located in the same directory. The authbridge image is included in this example (needed only for federated authentication), which needs to be accessible under the /AuthBridge subpath like in the example in Dundas BI and reverse proxies. When running other gateway hub, it should similarly be made accessible under /GatewayHub. Other container subpaths such as for export and Python are up to you but should then be set up in Dundas BI's configuration settings.

This example accesses a database server running outside of Docker for the Dundas BI application and warehouse databases. SSL is not configured in this example, but this is possible by mounting SSL certificate files in the NGINX container to refer to in the nginx.conf file.

Docker Compose Folder
    - docker-compose.yml
    - nginx.conf

nginx.conf

user  nginx;

events {
    worker_connections   1000;
}
http {
    server {
        listen 80;
        location /AuthBridge/ {
            proxy_pass http://dundas-bi-authbridge:8080/;
            proxy_http_version 1.1;
            proxy_set_header   Upgrade $http_upgrade;
            proxy_set_header   Connection keep-alive;
            proxy_set_header   Host $http_host;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Proto $scheme;
            proxy_cache_bypass $http_upgrade;

            proxy_set_header   X-Proxy-BasePath /AuthBridge;

            proxy_buffer_size  128k;
            proxy_buffers      4 256k;
            proxy_busy_buffers_size    256k;

            proxy_connect_timeout       86400;
            proxy_send_timeout          86400;
            proxy_read_timeout          86400;
            send_timeout                86400;
            client_max_body_size        500M;
        }
	  			  
        location / {
            proxy_pass http://dundas-bi-website:8080/;
            proxy_http_version 1.1;
            proxy_set_header   Upgrade $http_upgrade;
            proxy_set_header   Connection keep-alive;
            proxy_set_header   Host $http_host;
            proxy_cache_bypass $http_upgrade;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Proto $scheme;
            proxy_connect_timeout       86400;
            proxy_send_timeout          86400;
            proxy_read_timeout          86400;
            send_timeout                86400;
            client_max_body_size        500M;
        }
    }
}

docker-compose.yml

version: "3.1"

services:
   dundas-bi-website:
      image: dundas/dundas-bi-website:latest
      restart: always
      expose:
         - "8080"
      environment:
         - DUNDAS_BI_APP_DB_CONN_STRING=Data Source=192.168.0.111;User Id=DundasUser;Password=4321;Initial Catalog=Dundas BI Docker
         - DUNDAS_BI_APP_STORAGE=SqlServer
         - DUNDAS_BI_INTERNAL_APPLICATION_URL=http://192.168.0.111:9010/
         - DUNDAS_BI_EXTERNAL_APPLICATION_URL=http://192.168.0.111:9010/
   dundas-bi-scheduler:
      image: dundas/dundas-bi-scheduler:latest
      restart: always
      environment:
         - DUNDAS_BI_APP_DB_CONN_STRING=Data Source=192.168.0.111;User Id=DundasUser;Password=4321;Initial Catalog=Dundas BI Docker
         - DUNDAS_BI_APP_STORAGE=SqlServer
   dundas-bi-authbridge:
      image: dundas/dundas-bi-authbridge:latest
      restart: always
      environment:
         - DUNDAS_BI_APP_DB_CONN_STRING=Data Source=192.168.0.111;User Id=DundasUser;Password=4321;Initial Catalog=Dundas BI Docker
         - DUNDAS_BI_APP_STORAGE=SqlServer
   nginx:
      image: nginx:latest
      restart: always
      volumes:
         - ./nginx.conf:/etc/nginx/nginx.conf:ro
      depends_on:
         - dundas-bi-website
      ports:
         - 9010:80      

This Docker Compose file can be run by opening a command prompt, navigating to the Docker Compose folder and then running the following command:

docker-compose up

This will create the Dundas BI containers and start them. The website will be available through NGINX and port 9010 as defined in the docker-compose file above.

5.2. Scaling the Docker Compose project

The Docker Compose example above can easily be scaled. For example:

docker-compose up --scale dundas-bi-website=3

This will create 3 running replicas of the dundas-bi-website service, and handle the load balancing.

For more information about using Docker Compose, see Overview of Docker Compose in the Docker documentation.

5.3. Deploying to Kubernetes clusters using Docker

We recommend deploying to Kubernetes using Helm charts, but a docker-compose project like the above can also be used.

To use Docker Compose for deploying to Kubernetes instead of Helm charts, you can modify the docker-compose.yml example above like the following:

docker-compose.yml

version: "3.7"

services:
   dundas-bi-website:
      image: dundas/dundas-bi-website:latest
      restart: always
      environment:
         - DUNDAS_BI_APP_DB_CONN_STRING=Data Source=192.168.0.111;User Id=DundasUser;Password=4321;Initial Catalog=Dundas BI Docker
         - DUNDAS_BI_APP_STORAGE=SqlServer
         - DUNDAS_BI_INTERNAL_APPLICATION_URL=http://192.168.0.111:9010/
         - DUNDAS_BI_EXTERNAL_APPLICATION_URL=http://192.168.0.111:9010/
      deploy:
         replicas: 3
   dundas-bi-scheduler:
      image: dundas/dundas-bi-scheduler:latest
      restart: always
      environment:
         - DUNDAS_BI_APP_DB_CONN_STRING=Data Source=192.168.0.111;User Id=DundasUser;Password=4321;Initial Catalog=Dundas BI Docker
         - DUNDAS_BI_APP_STORAGE=SqlServer
   dundas-bi-authbridge:
      image: dundas/dundas-bi-authbridge:latest
      restart: always
      environment:
         - DUNDAS_BI_APP_DB_CONN_STRING=Data Source=192.168.0.111;User Id=DundasUser;Password=4321;Initial Catalog=Dundas BI Docker
         - DUNDAS_BI_APP_STORAGE=SqlServer
   nginx:
      image: nginx:latest
      restart: always
      volumes:
         - /C/DockerExample/nginx.conf:/etc/nginx/nginx.conf:ro

      ports:
         - 9010:80      

Next run the following command:

docker stack deploy --orchestrator=kubernetes -c docker-compose.yml dundasbi

Four pods are running as a result:

6. Compatibility

Dundas BI and its Docker images are compiled for the x64 (e.g., AMD64 or Intel 64) architecture, which means they will be emulated with QEMU when running in Docker or Kubernetes on other architectures such as ARM-based processors, including the Apple M series. Dundas BI Docker images have been found as of 2024 to run successfully on Apple M series processors, for example, however this relies on QEMU support for all required .NET functions.

7. See also

• Installing Dundas BI on Linux
• Docker Docs: Overview of Docker Compose
• Microsoft Docs: Kestrel web server implementation in ASP.NET Core
• Docker Hub: .NET Core docker images
• Docker Docs: Environment variables in Compose
• Docker Docs: docker run
• Orchestrating Dundas BI with Kubernetes and Helm charts
• Dundas BI and reverse proxies
• Dundas BI config file