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 running the different images. You can run images with either environment variables or mounted dbi.config files.
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 | Needed to run 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 | Needed to run the dt command line tool. |
dundas/dundas-bi-setup | Contains everything needed to create 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. (New in v8.0.1) |
dundas/dundas-bi-setup-orchestrator | The setup orchestrator is used to prevent multiple pods running the initialization at the same time. (New in v8.0.1) |
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.
3. Creating new Dundas BI application and warehouse databases
To create new application and warehouse databases, run the following command and replace {version} with the version 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 the same wizard used when deploying in Linux but only provides options used for container deployments. See Installing Dundas BI on Linux for more information about using the Dundas BI Deployment wizard.
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 handle database functionality that is part of the setup image. This feature is designed in the following way:
- If the connection string passed is to a database that doesn't exist, one will be created and initialized. The warehouse will be 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, nothing will be run and success will be returned.
Below are the arguments that can be passed to the handle database method:
Argument | Description |
---|---|
--DUNDAS_BI_APP_DB_CONN_STRING | The application database connection string. |
--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 the Dundas BI Configuration. This argument is optional. |
--DUNDAS_BI_EXTERNAL_APPLICATION_URL | Sets the external application url in the Dundas BI Configuration. 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 functionality could be called:
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"
4. Setting connection to Dundas BI databases
There are two different ways to set the connection string: either by setting environment variables, or using a mounted volume that places a dbi.config file.
4.1. Environment variables
Docker environment variables 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 the Dundas BI Docker container 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 will be the default. |
4.2. Mapped dbi.config file
An alternative to using environment variables is to use an un-encrypted dbi.config file. This can be done by mapping the file. The following is where the mapped file needs to be on the Docker container:
/usr/share/dundas/bi/Files/Container/www/BIWebsite/App_Data/dbi.config
For more information about mounting a file using volumes, see Use volumes in the Docker documentation.
4.3. Other environment variables
The following are additional environment variables, which set the respective Dundas BI configuration settings 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.4. Dundas BI website port
The dundas/dundas-bi-website uses port 8080, so published ports should map to this when using published ports. You can find examples demonstrating this in the following section.
4.5. Examples
The following command can be executed to start the Dundas BI website with environment variables and a published port:
docker run -it -p:80:8080 \ -e DUNDAS_BI_APP_DB_CONN_STRING="Data Source=localhost;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=localhost;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:
docker run -it \ -e DUNDAS_BI_APP_DB_CONN_STRING="Data Source=localhost;User Id=dbiuser;Password=pw;Initial Catalog=Dundas BI DockerTest" \ -e DUNDAS_BI_APP_STORAGE="SqlServer" \ dundas/dundas-bi-dt:8 healthcheck
The following command can be executed to start the Dundas BI website with a mounted dbi.config file:
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
5. Kestrel and NGINX
The dundas/dundas-bi-website container uses a Kestrel web server. It is expected that if you require more options like SSL you will use another service like NGINX, IIS or Apache to handle this. For more information regarding Kestrel web server and reverse proxies, see Dundas BI and reverse proxies, and 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. It is possible to run PostgreSQL or SQL Server as part of the docker-compose project, however this example does not cover that. Also, this example does not cover using SSL, however certificate can be mounted as volumes and to the NGINX service and can be added to 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
Deploying to Kubernetes is commonly done using Helm charts, but the docker-compose project above can also be used.
To use Docker 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:
6. 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 Linux services
- Dundas BI and reverse proxies