Skip to content

Getting started

Running with Docker

Architecture

There are three images in total each perform it's own function.

  • gui-dash - core static Dashboard Direct web app files served by the web server

  • gui-gateway - q server handles dashboards queries and manages list of dashboards and connection

  • gui-data - q data server manages demo datasets requested from the gui-gateway

Screenshot

Containers structure constrains

There are certain limitations in terms of container names especially for the gui-gateway that is referenced under this name in the gui-dash nginx config. The gui-dash image has an Nginx server running that is responsible for redirecting API calls from the web app to the gui-gateway app server. In its core is the nginx.config file that provides configuration to the Nginx and tells it redirects API calls to the gui-gateway image container. The container name is static and is baked in the docker image file.

Prerequisites

To run the images one would require one of the following operating systems Mac, Windows or Linux, capable of running following software:

  1. Docker
  2. Docker compose

Running steps

1) Make sure that Docker is running on the host system.

Note: Depending on the user operating system a different command prompt will need to be used. On Windows, we recommend using the Powershell.

2) Login to KX Docker registry with the login credentials provided to you to pull images

docker login registry.dl.kx.com -u username -p password

3) Create docker-compose.yml file to pull and execute docker images

An example Docker Compose file is provided here:

# docker-compose.yml
version: "3.7"
networks:
  kx:
    name: kx
    driver: bridge
volumes:
  gw-data:
services:
  gui-dash:
    image: "registry.dl.kx.com/kxi-gui-dash:0.8.2"
    ports: 
      - 9090:8080
    networks:
      - kx
    depends_on:
      - gui-gateway
  gui-gateway:   
    image: "registry.dl.kx.com/kxi-gui-gateway:0.8.1"
    ports:
      - 10001:10001
    networks:
      - kx
    # enable relative
    volumes:
      # Store app state in the gw-data volume
      - gw-data:/opt/kx/app/data
      ## Windows - create lic directory with valid kc.lic file
      #- ./lic:/opt/kx/lic
      ## Linux - make sure kc.lic file is present in ${HOME}/.qp.licenses
      #- ${HOME}/.qp.licenses:/opt/kx/lic
    depends_on:
      - gui-data
  gui-data:
    image: "registry.dl.kx.com/kxi-gui-data:0.8.0"
    ports:
      - 6812:6812
    volumes:
      - .:/opt/kx/app/sample/hdb/date
      ## Windows - create lic directory with valid kc.lic file
      #- ./lic:/opt/kx/lic
      ## Linux - make sure kc.lic file is present in ${HOME}/.qp.licenses
      #- ${HOME}/.qp.licenses:/opt/kx/lic
    networks:
      - kx

Note: This step requires that an appropriate kdb licence file is present on the host computer file system. The licence file is then mounted as a volume to the gui-gateway and qui-data. The recommended path to licence file on the host system vary between Linux and Windows.

To enable licence volume mounting uncomment appropriate line in the volumes property of the docker-compose.yml file above.

Make sure to enable the volumes: block in the gui-gateway section. Uncomment one of the following lines

Linux

Make sure that kc.lic is present in the ${HOME}/.qp.licenses directory

- ${HOME}/.qp.licenses:/opt/kx/lic 

Windows

In the same directory as the docker-compose.yml create the lic folder and paste your kc.lic

- ./lic:/opt/kx/lic

Info: For more information about the kbd+ licenses refer to those docs.

3) To start the app, from the directory with the docker-compose.yml script file run:

docker-compose up

Open in the web browser http://localhost:9090 to view running Dashboards app.

4) To stop the app Press ctl-c to exit running process in terminal and execute:

docker-compose down

Gateway State persistence

The gui-gateway container is responsible for managing Dashboards’ states, including connections, dashboards and URLs. These states are saved in a data file within the container. To preserve the state in case of failure, a volume, gw-data, is used to preserve a static data.

To view all available volumes run:

docker volume ls

To obtain information about a container, run:

docker volume inspect [volume name]

where [volume name] is the name generated by [directory-name]_gw.data. For example, direct-dash_gw_data

To remove the volume, stop all running gui-gateway containers with:

docker-compose down

Then run:

docker volume rm [volume name]

Download

 KX Dashboards Windows   Linux   Mac

Prerequisites

KX Dashboards is a minimal portable install only requiring kdb+ 3.4+ to run.

  1. Install kdb
  2. Define q as a command

Install and run

  1. Extract Dashboards zip file...
  2. Run KX Dashboards and a sample data process.
    Windows : click dash.bat to launch from the Dashboards folder
    Linux  and MacOS : manually open a terminal and launch the processes.
$ q sample/demo.q -u 1 &
$ q dash.q -p 10001 -u 1

Options

-secure restricts dash.q to access only functions defined on the .api namespace
-p listening port to serve KX Dashboards
-u 1 disables system commands and no access above start directory
-u usr-pwd sets a password file for basic authentication
-E TLS server mode

See the full command-line reference for more detailed explanation

Upgrade

Follow the steps to upgrade your existing installation to the latest version of dashboards.

Upgrade

Open Dashboards

Dashboard starts with a Demo page in Viewer mode by default. To enable the dashboard editor, insert /edit/ between the URL and #dashboard reference. This will enable menu options to create your own dashboard.

Screenshot

  1. Drag a component from the left and arrange on the central canvas, e.g. Data Grid
  2. Configure properties on the right, e.g. set a new Data Source to view data
  3. Add a form component and link it using View States

Continue adding components and setting properties to build, style and share interactive visualisations