🐳 Dockerize Toolchain (#66)

.github/workflows/docker-publish.yml

@@ -0,0 +1,30 @@
+name: Publish Docker image to Github Container Registry GHCR
+on:
+  release:
+    types:
+      - created
+
+jobs:
+  push_to_registry:
+    name: Push Docker image to GHCR
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+        # with: # we don't need this
+        #  submodules: "recursive"
+      - name: get version tag
+        run: |
+          VERSION=$(echo ${GITHUB_REF#refs/tags/})
+          echo "VERSION=$VERSION" >> $GITHUB_ENV
+      - name: Log in to GHCR
+        # the token has repo:write and package scope and expires on 2025-10-08
+        # https://github.com/Hochfrequenz/ebd_toolchain/settings/secrets/actions/GHCR_PUSH_TOKEN
+        run: echo "${{ secrets.GHCR_PUSH_TOKEN }}" | docker login ghcr.io -u hf-kklein --password-stdin
+
+      - name: Build and push
+        run: |
+          docker build -t ebd_toolchain:$VERSION .
+          docker tag ebd_toolchain:$VERSION ghcr.io/hochfrequenz/ebd_toolchain:$VERSION
+          docker push ghcr.io/hochfrequenz/ebd_toolchain:$VERSION

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY src .
+
+CMD ["python", "ebd_toolchain/main.py", "-i", "/container/ebd.docx", "-o", "/container/output", "-t", "json", "-t", "dot", "-t", "svg", "-t", "puml"]

README.md

@@ -11,17 +11,22 @@ Diese Entscheidungsbäume sind Teil eines regulatorischen Regelwerks für die de
 🇺🇸 This repository provides a Python script combining the libraries [ebdamame](https://github.com/Hochfrequenz/ebdamame) and [rebdhuhn](https://github.com/Hochfrequenz/rebdhuhn) in order to render [edi@energy](https://www.edi-energy.de) _Entscheidungsbaumdiagramme_ (EBD) as both machine-readable tables as well as corresponding graphs in `.svg` and `.uml` format.
 
 ## How to use EBD Toolchain
+You can either run the toolchain via Python (requires Docker AND Python to be installed on your machine).
+Or you can run the entire toolchain in a docker container (requires only Docker).
 
-### Install both libraries from PiPy:
+### Option A: Via Python + Kroki in a Docker Container
+
+#### Install both libraries from PiPy:
 ```bash
 pip install -r requirements.txt
 ```
-Further, make sure to have a local instance of [kroki](https://kroki.io) up and running via docker (localhost:8126) as described in the [rebdhuhn](https://github.com/Hochfrequenz/rebdhuhn) readme. Run the `docker-desktop` app on your local maschine and start the local kroki container via
+Further, make sure to have a local instance of [kroki](https://kroki.io) up and running via docker (localhost:8125) as described in the [rebdhuhn](https://github.com/Hochfrequenz/rebdhuhn) readme.
+Run the `docker-desktop` app on your local maschine and start the local kroki container via
 ```bash
 docker-compose up -d
 ```
-### Execute the EBD toolchain script:
- 
+#### Execute the EBD toolchain script:
+
 Run `main.py` using your IDE or inside a terminal session via
 ```bash
 python main.py
@@ -39,6 +44,46 @@ main.py -i <path to .doxc location> -o <output directory> -t json -t dot -t svg
 ```
 where `-i`, `-o` and `-t` denote the input directory path, the output directory path and the supported data format, respectively.
 
+### Option B: Docker only (no Python required)
+In this repository:
+1. create an `.env` file with a structure similar to [`env.example`](env.example).
+2. set the environment variables to meaningful values.
+3. Create a `docker-compose.yml` with the following content:
+```yaml
+services:
+  kroki:
+    image: yuzutech/kroki:0.24.1
+    ports:
+      - "8125:8000"  # Expose Kroki on port 8125 for rendering diagrams
+      # we hardcode 8125 because of https://github.com/Hochfrequenz/rebdhuhn/issues/205
+    healthcheck:
+      test: [ "CMD", "curl", "-f", "http://localhost:8000/health" ]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  scrape-and-plot:
+    image: ghcr.io/hochfrequenz/ebd_toolchain:latest
+    # If you run into 'manifest unknown' during docker pull, try replacing `:latest` with `:v1.2.3`.
+    # where v1.2.3 is the latest version of the GHCR image, which can be found here:
+    # https://github.com/Hochfrequenz/ebd_toolchain/pkgs/container/ebd_toolchain 
+    depends_on:
+      kroki:
+        condition: service_healthy
+    volumes:
+      - ${EBD_DOCX_FILE}:/container/ebd.docx
+      - ${OUTPUT_DIR}:/container/output
+    network_mode: host
+```
+4. Login to GitHub Container Registry (GHCR); Use a [Personal Access Token](https://github.com/settings/tokens/new) (PAT) to login that has access to this repository and at least `read:packages` scope
+```bash
+docker login ghcr.io -u YOUR_GITHUB_USERNAME
+```
+5. then run:
+```bash
+docker-compose up
+```
+
 ## How to use this Repository on Your Machine (for development)
 
 Please follow the instructions in our

docker-compose.yaml

@@ -1,7 +1,23 @@
-version: "3.8"
-
 services:
-  kroki: # see https://docs.kroki.io/kroki/setup/use-docker-or-podman/#_run_multiple_kroki_containers_together
+  kroki:
     image: yuzutech/kroki:0.24.1
     ports:
-      - "8126:8000"
+      - "8125:8000"
+      # hardcoded 8125 because: https://github.com/Hochfrequenz/rebdhuhn/issues/205
+    healthcheck:
+      test: [ "CMD", "curl", "-f", "http://localhost:8000/health" ]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  scrape-and-plot:
+    build: .
+    depends_on:
+      kroki:
+        condition: service_healthy
+    volumes:
+      - ${EBD_DOCX_FILE}:/container/ebd.docx
+      - ${OUTPUT_DIR}:/container/output
+    network_mode: host  # Allow the container to use the host's network
+    # this is also a side effect of https://github.com/Hochfrequenz/rebdhuhn/issues/205
+    # this prevents: requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8125): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fddfb8c9430>: Failed to establish a new connection: [Errno 111] Connection refused'))

env.example

@@ -1,2 +1,2 @@
-#Environment for Kroki
-KROKI_HOST=http://localhost:8126/
+EBD_DOCX_FILE=./edi_energy_mirror/edi_energy_de/FV2410/Entscheidungsbaum-DiagrammeundCodelisten-informatorischeLesefassung3.5KonsolidierteLesefassungmitFehlerkorrekturenStand31.07.2024_20250403_20240403.docx
+OUTPUT_DIR=./ebd_toolchain/machine-readable_entscheidungsbaumdiagramme/FV2404