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.

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

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

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

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

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

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

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