Enmeshed Backbone Data Dashboard

Usage

Releases are available as Docker images in the project's Github container registry. Containers are configured using the following obligatory environment variables:

• MSSQL_HOSTNAME: Hostname or IP-address of the backbone MSSQL server, e.g. localhost or 10.8.16.44.
• MSSQL_PORT: Port of MSSQL server, e.g. 1433.
• MSSQL_DB: Name of the backbone database to target within the MSSQL server, e.g. bkb-data.
• MSSQL_USER: Username, e.g. admin.
• MSSQL_PASSWORD: Password for above user, e.g. pa$$w0rd554.
• MSSQL_TARGET_ENCRYPT_CONNECTION: Specifies if SQL encryption should be used for the target database connection. Must be either true or false.
• MSSQL_TRUST_SERVER_CERTIFICATE: Specifies whether to use TLS to encrypt the target database connection and bypass walking the certificate chain to validate trust. Must be either true or false.
• DASHBOARD_HIDE_TEST_CLIENTS_DEFAULT: Configures whether to hide or show data associated with test clients by default. Must be either true or false.
• DASHBOARD_TEST_CLIENTS_REGEX: Configures which client IDs to consider test clients using a regular expression. For example, to match the client ID dev and all other client IDs which start with the prefix test- use the regular expression dev|test-.*.
• DASHBOARD_APP_CLIENTS_REGEX: Configures which client IDs to consider app clients using a regular expression. For example, to match the client ID app-dev and all other client IDs which start with the prefix app- use the regular expression app-dev|app-.*. Client IDs not matched by the pattern are considered connector clients.

The dashboard is exposed at port 5000 by default. For example, to launch a dashboard listening at http://localhost:80, which connects to a MSSQL server with the above exemplary credentials the following command may be used:

docker run --rm                                     \
	-p 80:5000                                      \
	-e MSSQL_HOSTNAME='10.8.16.44'                  \
	-e MSSQL_PORT='1433'                            \
	-e MSSQL_DB='bkb-data'                          \
	-e MSSQL_USER='admin'                           \
	-e MSSQL_PASSWORD='pa$$w0rd554'                 \
	-e MSSQL_TARGET_ENCRYPT_CONNECTION='false'      \
	-e MSSQL_TRUST_SERVER_CERTIFICATE='true'        \
	-e DASHBOARD_HIDE_TEST_CLIENTS_DEFAULT='true'   \
	-e DASHBOARD_TEST_CLIENTS_REGEX='dev|test-.*'   \
	-e DASHBOARD_APP_CLIENTS_REGEX='app-dev|app-.*' \
	"ghcr.io/js-soft/nmshd-bkb-data-dashboard:latest"

The dashboard server uses multi-process load balancing by default. The number of workers defaults to 4 can be set via the environment variable DASHBOARD_NUM_WORKERS. If your method of deployment has other means of horizontal scaling the built-in load balancing can be disabled by setting the number of workers to 1.

Dev Setup

1. Clone the repository, ensure Python ≥3.12, Poetry and the Work Sans font are installed. Then install all dependencies and activate your virtual environment.

   poetry install --with dev
   poetry shell

2. Provide the location and credentials for the backbone database server to use during development by setting the environment variables listed in the usage instructions above. DASHBOARD_NUM_WORKERS is not used in a dev setting.

3. (Optional) A local backbone mssql server and database can be bootstrapped from a local .bacpac backup file using dev/bootstrap-mssql.docker-compose.yml. Check the file for information on what to configure.

4. Start the dashboard server locally via python main.py. The hostname and port default to localhost and 5000, respectively. To override these defaults use the environment variables:

   • DEV_DASHBOARD_HOSTNAME: Hostname or IP-address of dashboard server
   • DEV_DASHBOARD_PORT: Port of dashboard server