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.

Tip
Deploy to Kubernetes using Helm charts instead of the steps shown below to take advantage of options such as auto-scaling and to allow many aspects of configuration to be handled automatically including the setup of the various images.

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:

RepositoryDescription
dundas/dundas-bi-website Runs the Dundas BI application website. See the tags section below.
dundas/dundas-bi-scheduler Runs the Dundas BI scheduler service for features including data cube storage jobs and notifications.
dundas/dundas-bi-export Exports content to PDF, image, Excel, and other formats, including for notifications, in version 23.2 and higher.
dundas/dundas-bi-python Provides the metric set natural language assistant and Python transform functionality in version 23.2 and higher.
dundas/dundas-bi-storage Optionally performs data cube storage tasks separately from the main website in version 23.3 and higher.
dundas/dundas-bi-full Runs the Dundas BI website with the scheduler, authbridge, and other functionality included in the same container.
dundas/dundas-bi-dt Used for running the dt command line tool.
dundas/dundas-bi-setup Creates and upgrades the application and warehouse databases used to run Dundas BI.
dundas/dundas-bi-authbridge Needed to run federated authentication when not using the Dundas BI full image.
dundas/dundas-bi-gateway-hub Needed to be able to connect to on-premise data sources through gateways.
dundas/dundas-bi-setup-orchestrator The setup orchestrator is used to prevent multiple pods running the initialization at the same time.

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.

Note
There are certain known limitations when Dundas BI runs on Linux, including these images. Dundas BI and its Docker images also rely on the x64 processor architecture – for details, see the Compatibility section below.

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.

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.

The Dundas BI container setup wizard
The Dundas BI container setup wizard

Note
If you are asked for your email and installation key, you can find these in the My Account section of the support site.

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).

Dundas BI Architecture - Application Database (App DB)
Dundas BI Architecture - Application Database (App DB)

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:

ArgumentDescription
--DUNDAS_BI_APP_DB_CONN_STRING The application database connection string. For syntax details, see the following section.
--DUNDAS_BI_APP_STORAGE Represents the type of database connection to use.
Valid values are SqlServer, or Postgres. If no value is supplied, SqlServer will be the default. This argument is optional.
--DUNDAS_BI_ADMIN_PASSWORD The password for the admin user. In the case of database creation, this will be used to initialize the admin password. If the database already exists, the admin password will be reset to this value. This argument is optional.
--DUNDAS_BI_ADMIN_EMAIL_ADDRESS The email address for the admin user (for Dundas BI versions 11 and up). This argument is optional.
--DUNDAS_BI_INTERNAL_APPLICATION_URL Sets the Internal Application URL in Dundas BI's configuration settings (described below). This argument is optional.
--DUNDAS_BI_EXTERNAL_APPLICATION_URL Sets the External Application URL in Dundas BI's configuration settings (described below). This argument is optional.
--DUNDAS_BI_DOCKER_EMAIL The Docker email, only required when creating new Dundas BI databases.  In order to create the databases you will need to use an email and key available in the My Account section of the support site.
--DUNDAS_BI_DOCKER_KEY The Docker key, only required when creating new Dundas BI databases. In order to create the databases you will need to use an email and key available in the My Account section of the support site.

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:8 --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"

Tip
This feature is also used in Dundas BI Helm charts to create and upgrade databases for you automatically.

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:

ArgumentDescription
--DUNDAS_BI_SAMPLE_NAME The type of Dundas-provided sample to add to the instance (for Dundas BI versions 11 and up).
Valid values are Usage, Performance, or Getting Started.

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

Note
It is not recommended to set system wide environment variables when using Dundas BI as it will affect all instances of Dundas BI installed on that machine.

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:

Environment VariableDescription
DUNDAS_BI_APP_DB_CONN_STRING Represents the connection string to the Dundas BI application database.
DUNDAS_BI_APP_STORAGE Represents the type of database connection to use.
Valid values are SqlServer, or Postgres. If no value is supplied, SqlServer is the default.

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.

Tip
You can use the Scheduler Service Status health check to determine whether the scheduler was able to connect to the website server since last starting.

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:

Environment VariableDescription
DUNDAS_BI_INTERNAL_APPLICATION_URL Sets the Dundas BI internal application URL.
DUNDAS_BI_EXTERNAL_APPLICATION_URL Sets the Dundas BI external application URL.

4.5. Examples

Note
host.docker.internal is used as an example and can require extra configuration for Docker Engine: --add-host host.docker.internal:host-gateway. These examples use backslashes for readability, but they should be removed if using a Windows Command Prompt as they are not compatible.

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:8

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:8

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:8 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:8

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;
        }
    }
}

Note
For Dundas BI version 9 and earlier, you need to change X-Proxy-BasePath above to X-Proxy-BaseUri for specifying the /AuthBridge path. This older header name will also work in newer versions.

docker-compose.yml

version: "3.1"

services:
   dundas-bi-website:
      image: dundas/dundas-bi-website:8
      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:8
      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:8
      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:8
      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:8
      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:8
      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:

The kubectl get pods command after deployment.
The kubectl get pods command after deployment.

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.

At the time of this writing, Dundas BI Docker images are currently not compatible with ARM-based architectures due to errors such as Function not implemented that occur because QEMU does not emulate all required .NET functions.

7. See also

Dundas Data Visualization, Inc.
400-15 Gervais Drive
Toronto, ON, Canada
M3C 1Y8

North America: 1.800.463.1492
International: 1.416.467.5100

Dundas Support Hours:
Phone: 9am-6pm, ET, Mon-Fri
Email: 7am-6pm, ET, Mon-Fri