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, and use scaling and high availability options such as Kubernetes. Containers also isolate Dundas BI from other apps and your server's operating system and allow you to manage the container resources.

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

Tip
You can deploy using Helm charts instead of the steps shown below to run Dundas BI images on Kubernetes and allow many aspects of configuration to be handled automatically.

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.
dundas/dundas-bi-scheduler Runs the Dundas BI scheduler service for features including data cube storage jobs and notifications.
dundas/dundas-bi-full Runs the Dundas BI website with the scheduler and authbridge also included in the same container.
dundas/dundas-bi-dt Used for running the dt command line tool.
dundas/dundas-bi-setup Creates 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-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 and use the 3.1-bionic tag, which uses the Ubuntu 18.04 operating system.

There are certain known limitations when Dundas BI runs on Linux, including these images.

Note
Dundas BI and its Docker images rely on the x64 processor architecture. For details, see the Compatibility section below.

3. Creating new Dundas BI application and warehouse databases

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

To create new application and warehouse databases, run the following command and replace {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. This is like the wizard used when deploying Dundas BI directly on Linux, but only provides options used for container deployments.

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

Note
You will need to use the email and key listed for Docker in the My Account section of the support site.

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 to create new databases is to use the --handledatabase option with 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 admin password. In the case of creation the admin password will be initialized to this, if the database already exists the admin password will be reset to this value. 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"

Note
This feature is also used in Dundas BI helm charts to create and upgrade databases.

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

Note
Setting the connection for the Dundas BI databases is required for dundas/dundas-bi-website, dundas/dundas-bi-scheduler, dundas/dundas-bi-authbridge, and dundas/dundas-bi-dt. It is not required for starting dundas/dundas-bi-setup.

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

The Internal and External Application URL configuration settings in Dundas BI need to be set for certain functionality to work correctly. You can set these 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). 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 it was able to connect to the website server since the scheduler last started.

If you prefer to set these 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
These examples use backslashes for readability, but they should be removed if using a Windows Command Prompt as they are not compatible. host.docker.internal is used as an example and can require extra configuration for Docker Engine: --add-host host.docker.internal:host-gateway.

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

Tip
You can set a restart policy when using docker run (e.g., docker run --restart=always...) or a compose file if the container should automatically start when Docker or the host restarts.

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 that live in the same directory. In this example it assumes that you have a Dundas BI application, and warehouse database outside of Docker that is accessible, and already initialized.

This docker-compose example does not include running the PostgreSQL or SQL Server database or configuring SSL, however these are also possible. SSL certificate files can be mounted as volumes 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-BaseUri /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:8
      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
      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
      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
      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
      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
      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
      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
      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 on Docker on other architectures such as ARM-based processors like Apple M1 Macs. At the time of this writing, error messages such as Function not implemented occur because QEMU does not emulate all required functions for .NET, which the Dundas BI website relies on, meaning Dundas BI Docker images are currently not compatible with ARM-based architectures.

7. See also

Dundas Data Visualization, Inc.
500-250 Ferrand Drive
Toronto, ON, Canada
M3C 3G8

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