Herbie - The Semantic Laboratory Notebook & Research Database

Herbie is the electronic laboratory notebook (ELN) and research database developed at the Helmholtz-Zentrum Hereon to facilitate the digitalization efforts within several institutes. Herbie builds upon semantic technologies like OWL and SHACL to offer a user-friendly interface to the RDF ecosystem.

Main Features

Herbie provides a platform to collaboratively work on a shared knowledge graph. It is implemented as a wrapper around an RDF triple store, offering additional features like versioning, user handling, and management of access rights.

Import RDF graphs

Users can upload any RDF graph to Herbie in one of the standard formats like Turtle or JSON-LD. This includes, in particular vocabularies and ontologies, as well as documents containing SHACL shapes.

Generate web forms

Moreover, Herbie offers an advanced form generation feature which turns all SHACL documents into user-friendly web forms. By filling out and submitting these forms, end users can contribute to a fully semantically annotated knowledge graph without having to deal with the intricacies of RDF.

Extract data

To eventually extract the entered knowledge as tabular data (CSV), JSON, or in graph form, Herbie offers a default SPARQL endpoint as well as a simple user interface to interactively create advanced queries which are run on the (virtual) knowledge graph belonging to the requesting user.

Target Audience

Herbie provides the means to offer structured, well-adapted protocols to capture standardized processes and offering an easy and flexible documentation platform. It can be flexibly adapted to the needs of any (scientific) domain (e.g. material science, biology, medicine) making it a perfect choice for interdisciplinary groups who want to create a rich and connected data pool.

Contents

[[TOC]]

Run a local Demo

You can try out Herbie by running a local demo version using docker and docker compose so make sure you have installed docker and docker-compose on your system.

Once installed you can run the Demo instance of Herbie using the following commands:

git submodule update --init
./scripts/build-docker-images.sh
docker compose -f compose.prod.yaml up -d
docker compose -f compose.prod.yaml run django python manage.py migrate
docker compose -f compose.prod.yaml run django python manage.py runscript seed_development_database

After doing this, you should be able to access Herbie on http://localhost:2194/ and log in as admin with password secret. There are also three user accounts available, alice, bob, and cindi, also with password secret.

Using the Demo

We will give a quick tour of what is possible with Herbie. This includes:

• Uploading OWL ontologies and SHACL documents
• Creating data graphs using these documents
• Getting an overview of all entered data
• Performing advanced queries

Uploading OWL ontologies and SHACL documents

To get an idea of what is possible with Herbie, you can start by importing the exemplary RO-Crate coffee.zip from https://codebase.helmholtz.cloud/hereon-mb/ontologies/coffee.

This crate contains a small ontology to model a coffee brewing process as well as SHACL documents which Herbie can use to offer web forms for entering data which uses this ontology.

To import this file you first have to create a new workspace. Click on Create workspace and in the dialog enter a name and click Create workspace. Then click on this newly created workspace to open it. Now click on the blue +-button at the top left of the page and then select Import RO-Crate from the menu. Select the zip file, and if everything was successful you should now see a number of documents in Herbie.

Creating data graphs using these documents

Now it is possible to, for example, enter data for a "Roasting"-proces. To do this, click again on the +-button at the top left of the page, but select Document from the menu this time. A dialog will open up listing all possible kinds of entities you can create. To continue with our example, click on the entry Roasting.

A web form opens, in which you can enter all the parameters of the coffee roasting process. When you are finished click on Submit at the bottom of the page, to finally persist all the data you have entered in Herbie. When Herbie has finished persisting this entry in the database, you should see a card view of your entry.

You could now continue, to create more entries, for example for the grinding, brewing or tasting processes.

Getting an overview of all entered data

After entering your data into Herbie, you probably want to be able to find the entries you have added. One way to do this, is to open the explorer by clicking on Explorer on the navigation rail on the left side.

On the left side you should now see a list of all available classes within our currently active workspace. Select the Roasting class, which opens another list next to the list of classes, containing all instances of the class which you have selected. Select one of these to see some information about this instance on the right of the screen.

In particular, you will get a link to the document which you have created earlier to add this instance to Herbie.

Performing advanced queries

To perform more advanced queries against the knowledge graph you have created with Herbie, we have integrated the Sparklis query builder frontend. Click on Sparklis on the navigation rail on the left, to open up this query builder.

When you uploaded your ontologies and created some instances, you should be able to build queries in Sparklis to retrieve this data.

Setup the development environment

[!important] The project consists of multiple subsystems, that can be started using some helper scripts. These helper scripts expect an environment in the .env folder. Therefore the python environment has to be called venv and be locatet in the root folder, or the helper scripts stop working. Conda or other environtment managers are NOT SUPPORTED by the helper scripts for now.

[!note] If you have conda installed, you should disable autoactivation of the base environment to avoid interference with the venv environment:

conda config --set auto_activate_base false

To create a local development environment for Herbie you need to install Docker, Python and NodeJS.

1. Update the git submodules

   git submodule update --init

2. Create the python environment and install all dependencies

   python -m venv .venv
   source .venv/bin/activate
   pip install --upgrade uv
   uv sync

3. Create an example env file and activate it

   cp .env.example .env

4. Start the development environment

   In three different shells run the following commands:

   docker compose up

   source .venv/bin/activate
   set -a; source .env; set +a
   celery -A eln worker -l DEBUG

   source .venv/bin/activate
   set -a; source .env; set +a
   python manage.py migrate && python manage.py runserver

5. Initialize the development environment (optional)

   If you are running your development environment for the first time, you might want to initialize the database by running:

   set -a; source .env; set +a
   python manage.py runscript seed_development_database

   This will create a super user admin and three normal user accounts alice, bob, cindi, all with password secret.

6. Compile and run the frontend

   [!note] Please make sure to install the node dependencies using npm ci (what's this?) to not interfere with the package versions and dependencies. Please do not use npm install.

   Install the required packages and compile the assets

   npm ci
   npm run gen:elm-spa-gen:gen
   
   cd frontend
   npm ci

   Then run the following in another shell:

   cd frontend
   npm run watch:webpack

   and in another shell:

   cd frontend
   npm run watch:elm

7. Now, your local Herbie instance should be available at http://localhost:8000/.

8. Convenient start-script

   Now everything is setup, the next time you want to start the development environment, you can use the convenience startup script to automatically start every script in tmux

   [!note] install tmux to be able to use the convenience start-up script (Linux only)

   ./dev_scripts/run.sh

   [!note] If you are on WSL and did the manual setup already or just don't wish to use the setup script, please create a empty file named .setup in herbie's main directory before use or this might cause unexpected issues)

Set Up Docker + Herbie on Windows using WSL

Open "Windows-Features" and make sure "Windows Subsystem For Linux" is checked. In a Terminal type

wsl --update

followed by

wsl --install -d [ CHOOSE Debian or Ubuntu]

Type Debian or Ubuntu in a Terminal to launch WSL clone the Herbie Repository and switch to directory

git clone https://codebase.helmholtz.cloud/hereon-mb/herbie.git
cd herbie

[!warning] The docker group grants root-level privileges to the user. For details on how this impacts security in your system, see Docker Daemon Attack Surface. It is recommended to run docker in rootless mode at user level to improve system security

Then you need to create and add yourself to the docker group

sudo groupadd docker
sudo usermod -aG docker $USER

Convenience Setup Script

[!note] The setup script requires apt or apt-get to install the required packages, so it only works on Debian based distros. It is strongly recommended to look into the script before running it, especially on already existing Linux installations. The script removes and reinstalls packages, adds new package sources to apt and creates users, groups and grands root permissions to the user through docker

You can use the Convenience setup Script (tested on WSL Ubuntu-24.04)

./dev_scripts/setup.sh

Manual Setup

Install Docker Engine (preferably use APT Repo for easy Maintenance/Updates). Start Up Herbie Docker Stack

git submodule update --init
./scripts/build-docker-images.sh
docker compose -f compose.prod.yaml up -d
docker compose -f compose.prod.yaml run django python manage.py migrate
docker compose -f compose.prod.yaml run django python manage.py runscript seed_development_database

After doing this, you should be able to access Herbie and log in as admin with password secret. If this succeeds, continue as mentioned above on your working WSL setup, congrats!

Side Notes

Remember to register your data after installing git (only replace text, leave double quotes)

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

For easier Management of git Credentials within WSL you can use the Windows Git Credential Manager instead

• If GIT installed is >= v2.39.0

  git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

• else if GIT installed is >= v2.36.1

  git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"

• else if version is < v2.36.1 enter this command:

  git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager-core.exe"

Potential Issues/Fixes

Git Credential Manager

If Git was installed without Administrator Priviliges in it's default configuration, the Path for the Git Credential Manager changes. Fix:

git config --global credential.helper "/mnt/c/Users/${YOUR USERNAME}/AppData/Local/Programs/Git/mingw64/bin/git-credential-manager.exe"

Releases and source code

You can find all releases of Herbie as well as its latest source code at codebase.helmholtz.cloud/hereon-mb/herbie.

Contact

Do not hesitate to contact us if you have questions, comments, or feedback. You can reach us at [email protected].

Status

This is actively developed by members of the Institute of Metallic Biomaterials and the Institute of Membrane Research at Hereon.

LICENSE

This program is subject to the terms and conditions for non-commercial use of ELN. You can find the license text in the file LICENSE.en and under https://codebase.helmholtz.cloud/hereon-mb/herbie/-/raw/main/LICENSE.en. If you have any questions or comments, you can contact us at hereon at [email protected] or by mail at Helmholtz-Zentrum hereon GmbH, Max-Planck-Straße 1, 21502 Geesthacht, Germany.

Commercial use

Please get in contact with us if you would like to use Herbie commercially. You can reach us at [email protected].

Authors

Development is led by Catriona Eschke and Fabian Kirchner, within the group of Regine Willumeit-Römer, with additional contributions by

• Anke-Lisa Höhme
• Miłosz Meller
• Alexander Foremny
• Severin Gescher
• Martin Held
• Sayed Ahmad Sahim
• Sai Harshath Maddali.

Citing

Kirchner, F., Eschke, C., Höhme, A.-L., Meller, M., Foremny, A., Gescher, S., Held, M., Sahim, S. A., Maddali, S. H. & Willumeit-Römer, R. (2026). Herbie - The Semantic Laboratory Notebook & Research Database (0.3). Zenodo. https://doi.org/10.5281/zenodo.18254444