Apps

The applications which are provided by blackbar consist of

  1. A frontend for generating training data & manual validation of results (Inception) and a place for storing models which allow to detect personally identifiable information (Minio) (link)
  2. A cockpit application to easily create projects, upload data, auto anonymize and pseudonymize, build and maintain models. And web applications to show the results of the anonymization and pseudonymization, run and deploy models (apps using Shinyproxy) (link)

Inception and Minio

Inception and Minio are integrated in one docker image allowing you to deploy the annotation and model storage framework quickly as shown below:

docker pull ghcr.io/bnosac/blackbar-inception-minio:latest
docker run --rm -it --name blackbar-apps-inception \
    -p 9901:9001 \
    -p 9900:9000 \
    -p 8180:8080 \
    --env-file .env \
    ghcr.io/bnosac/blackbar-inception-minio
  • Inception
    • Runs at port 8080
    • You can log in with the values that you have set with the environment variables INCEPTION_USERNAME and INCEPTION_PASSWORD as specified in .env. This will create the admin user and the container has the remote-api enabled which blackbar uses to communicate in the apps. Note: don’t use any special characters in INCEPTION_PASSWORD.
    • You can enable preauthentication by setting the environment variable INCEPTION_AUTHENTICATION=preauth in .env if you are in a reverse proxy setting explained here and pass on the user name in the remote_user header. These new users are by default annotators and can be upgraded to admin or project manager of an annotation project.
    • By default this container uses 750Mb RAM which is good if you keep your Inception projects manageable (e.g. less than 500 docs). You can increase the memory which Inception is allowed to use by setting JAVA_MEM_OPTS=-XX:MaxRAMPercentage=80
  • For Minio
    • The frontend which is also known as the console is configured to run at port 9001
    • The minio server S3 environment is configured to run at port 9000
    • You can log in with the values that you have set with the environment variables BLACKBAR_S3_ACCESS_KEY_ID and BLACKBAR_S3_SECRET_ACCESS_KEY in .env

The docker container stores the files on Minio internally in the container in folder /data, while the annotations from Inception are stored at folder /export. Make sure you persist these folders such that at container restart, the models and annotations are not gone. E.g. with the following volumes.

docker run -d --name blackbar-apps-inception \
    -p 9901:9001 \
    -p 9900:9000 \
    -p 8180:8080 \
    -v $(pwd)/minio:/data \
    -v $(pwd)/inception:/export \
    --restart always \
    --env-file .env \
    ghcr.io/bnosac/blackbar-inception-minio
docker logs blackbar-apps-inception

Inception alongside MariaDB

By default the above setup uses a HyperSQL database to store it’s metadata, you can make this more reliable by using Inception alongside your own MariaDB to store the metadata of Inception.

Note that the annotations which you perform in Inception are stored in xml/xmi files on the host and not in the database.

Inception with an external database

If you have already a MariaDB running, you need to make sure Inception can talk to it as outlined below.

  • make sure an inception user is allowed full rights on a database called inception in your MariaDB which should be configured for 4-byte UTF-8 character set (utf8mb4) and a case sensitive collation (utf8mb4_bin)
CREATE DATABASE inception DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
CREATE USER 'inception'@'localhost' IDENTIFIED BY 'inception_db_password';
GRANT ALL PRIVILEGES ON inception.* TO 'inception'@'localhost';
FLUSH PRIVILEGES;
  • specify the following environment variables in .env when launching the container and replacing the URL/password according to your setup.
INCEPTION_DB_URL=jdbc:mariadb://localhost:3306/inception?useSSL=false&serverTimezone=UTC&useUnicode=true&characterEncoding=UTF-8
INCEPTION_DB_USERNAME=inception
INCEPTION_DB_PASSWORD=inception_db_password
INCEPTION_DB_DIALECT=org.hibernate.dialect.MariaDB106Dialect
INCEPTION_DB_DRIVER=org.mariadb.jdbc.Driver

Inception with non-external database

If you don’t have an existing MariaDB, you can use the image ghcr.io/bnosac/blackbar-inception-mariadb which will run a MariaDB under supervisord alongside the Inception app and the Minio storage engine. In that case make sure you as well create a volume which persistently stores the MariaDB as shown below.

docker pull ghcr.io/bnosac/blackbar-inception-minio-mariadb:latest
docker run -d --name blackbar-apps-inception \
    -p 9901:9001 \
    -p 9900:9000 \
    -p 8180:8080 \
    -v $(pwd)/s3:/data \
    -v $(pwd)/inception:/export \
    -v $(pwd)/inception-db:/var/lib/mysql \
    --restart always \
    --env-file .env \
    ghcr.io/bnosac/blackbar-inception-minio-mariadb

In .env make sure you have set the environment variables INCEPTION_DB_USERNAME/INCEPTION_DB_PASSWORD. These will be used as credentials to Inception but also as credentials to the MariaDB. No need to set INCEPTION_DB_URL, INCEPTION_DB_DIALECT, INCEPTION_DB_DRIVER in that case.

Web applications using Shinyproxy

blackbar contains several applications which can be used to

  • Monitor the evolution and progress of annotations
  • Easily upload and pre-annotate and pseudonymize texts
  • Monitor, train and run models which detect personally identifiable information
  • See how the anonymization and pseudonymization work on your own texts
  • Administrative tasks on the automation of the anonymization and pseudonymization

The applications are made available as Docker-based apps which are deployed behind ShinyProxy.

For readers who are not familiar with ShinyProxy, it launches for each person which starts an app a separate Docker container such that the apps are isolated. For this ShinyProxy needs to have access to the Docker daemon and the default user under which the Docker container runs (which is for our Docker images user blackbar) needs to be part of the docker group such that the apps can be launched and as well the apps can launch anonymization and pseudonymization runs or backend flows using Docker.

In our setting ShinyProxy is as well deployed as a docker container which requires to create a network with exactly the name blackbar-apps-network such that it knows which webapps has started up.

In order to launch the webapps, pull the image, create the network and start up the container as shown below such that it can connect to the docker daemon.

docker pull registry.datatailor.be/blackbar-shinyproxy:latest
docker network create --driver bridge blackbar-apps-network
DOCKER_GROUP=$(getent group docker | cut -d: -f3)
docker run -d --name blackbar-webapps \
  -p 8280:8080 \
  --net blackbar-apps-network --group-add $DOCKER_GROUP -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart always \
  --env-file .env \
  registry.datatailor.be/blackbar-shinyproxy

This will launch the webapps on port 8080.

In order to add authentication it is advised to enable OIDC integration as explained here.

  • There are 3 user groups: ‘blackbar-admin’, ‘blackbar-developer’ and ‘blackbar-user’.
  • ‘blackbar-admin’ and ‘blackbar-developer’ have access to all apps including the apps which allow to develop the webapps and blackbar-admin has also access to see which containers are running
  • ‘blackbar-user’ has only access to the applications which allow to inspect the data

Another option for testing is to use environment variables which will be passed on to ShinyProxy, allowing to authenticate with a simple login.

The below example launches the apps with a simple authentication with one user which is part of the blackbar-admin group and another user which is part of the blackbar-developer group.

docker run -d --name blackbar-webapps \
  -p 8280:8080 \
  --net blackbar-apps-network --group-add $DOCKER_GROUP -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e PROXY_AUTHENTICATION="simple" \
  -e PROXY_USERS_0_NAME="blackbar" -e PROXY_USERS_0_PASSWORD="yourpassword" -e PROXY_USERS_0_GROUPS="blackbar-admin" \
  -e PROXY_USERS_1_NAME="bbdev123" -e PROXY_USERS_1_PASSWORD="yourpassword" -e PROXY_USERS_1_GROUPS="blackbar-developer" \
  --restart always \
  --env-file .env \
  registry.datatailor.be/blackbar-shinyproxy

After you logged in with the user that you provided, you can visit the applications.

Prefect

In order to automate processes, blackbar integrates with Prefect. This allows the setup to anonymize and pseudonymize all the documents in the database in a continuous fashion. The integration with Prefect is usefull as well for the iterative model improvement as well as for the final pseudonymization proces. For that reason you can launch Prefect automations from the blackbar cockpit app.

Either you can use Prefect Cloud or you can run Prefect locally. The below setup launches Prefect locally.

  • The blackbar environment uses Prefect 3.4.22.
  • You can launch Prefect as follows, which makes it compatible with the reverse proxy setting explained here
  • In the below case
    • the Prefect UI would then be available at https://blackbar.datatailor.be/automation/prefect/
    • the Prefect API would then be available at https://blackbar.datatailor.be/prefect-server/api
docker pull prefecthq/prefect:3.4.22-python3.10
docker run --name blackbar-prefect -p 4200:4200 -d \
  -e PREFECT_UI_URL="https://blackbar.datatailor.be/prefect/" \
  -e PREFECT_API_URL="https://blackbar.datatailor.be/prefect-server/api" \
  -e PREFECT_UI_SERVE_BASE="/automation/prefect/" \
  -e PREFECT_SERVER_API_BASE_PATH="/prefect-server/api" \
  prefecthq/prefect:3.4.22-python3.10 -- prefect server start --host 0.0.0.0

In this setting you would need to set the following in your .env when you start up the webapps

PREFECT_ENVIRONMENT=local
PREFECT_API_URL=https://blackbar.datatailor.be/prefect-server/api
PREFECT_WORKPOOL=default-agent-pool

For this to work. In the Prefect UI at your site e.g. https://blackbar.datatailor.be/automation/prefect/, create a process workpool with a name that you choose e.g. default-agent-pool.

Extra AI apps

Next to the core apps, there are as well AI apps which serve as an example of how the pseudonymized text can be use and as well as an example how further apps can be integrated in the setup.

Chat to patient documents

One app is the chat to patient documents app which allows to chat and ask questions on pseudonymized documents.

  • This app is only usefull if you have a locally running LLM model served through Ollama.
  • The app allows to fetch all pseudonymized documents of a patient or just one document.
  • When you press the button on sending the data to the LLM, it will prompt the LLM to generate a summary of the health condition of the patient alongside treatments and follow up.
  • A person using the app can next ask questions about the documents of the patient.

If you have an existing GPU with Ollama running in your datacenter you can just point to the right URL when starting up the docker container with the apps by adding the environment variables of the URL and the model name. If you have just a CPU, you could see the behaviour of the app by pulling and running the following image which has a quantised version of ´gemma3-12b´ and by adding the OLLAMA_BASE_URL and OLLAMA_MODEL to the environment variables when launching blackbar-webapps.

docker pull ghcr.io/bnosac/blackbar-ollama-gemma3-12b-it-qat
docker run -d -p 11434:11434 --name ollama ghcr.io/bnosac/blackbar-ollama-gemma3-12b-it-qat
OLLAMA_BASE_URL=https://{deid.yourcompany.eu}/ollama/
OLLAMA_MODEL=gemma3:12b-it-qat

The above image contains version of gemma3. You can take a smaller gemma3-4b model to start with as well if you have less RAM. Or a bigger one e.g. blackbar-ollama-gemma3-27b-it-qat if you have a GPU, gemma3 is an good model to run on a single GPU but for this you will need another container with GPU acceleration enabled.

docker pull ghcr.io/bnosac/blackbar-ollama-gemma3-4b-it-qat
docker run -d -p 11434:11434 --name ollama ghcr.io/bnosac/blackbar-ollama-gemma3-4b-it-qat
OLLAMA_BASE_URL=https://{deid.yourcompany.eu}/ollama/
OLLAMA_MODEL=gemma3:4b-it-qat

Note on access to Docker host

The apps allow to launch docker containers to train models, do anonymization and pseudonymization in an automated way. For this the docker user in the containers called blackbar needs to have access to the docker socket /var/run/docker.sock.

In case you notice the apps do not seem to have access to the docker socket, log in to the docker container with the root user (docker exec -u root -it bash) when you launch the cockpit app or vscode app and make sure it has access to the docker socket as follows.

setfacl --modify user:blackbar:rw /var/run/docker.sock

From the moment you have done this, the blackbar user will for future usage of the apps have access to the docker socket and launch containers. If you don’t trust this you can remove the access (setfacl -x user:blackbar: /var/run/docker.sock), but you lose the ability to build models and perform automated anonymization and pseudonymization.