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:
Repository | Description |
---|---|
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-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.
There are certain known limitations when Dundas BI runs on Linux, including these images.
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.
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:
Argument | Description |
---|---|
--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"
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:
Argument | Description |
---|---|
--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
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 Variable | Description |
---|---|
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.
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 Variable | Description |
---|---|
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
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 the gateway hub, it should similarly be made accessible under /GatewayHub.
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: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:
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 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 .NET functions that the Dundas BI website relies on, meaning Dundas BI Docker images are currently not compatible with ARM-based architectures.
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