chore: document application setup (for partners) by mirdono · Pull Request #101 · lblod/app-decide

mirdono · 2026-05-18T13:54:36Z

This PR extends the existing documentation to better support partners to set up their own instance of the DECIDe application. This initially focuses on the city of Bamberg who are primarily interested in use cases 0.1 (policy impact report) and 2 (smart search). Further guidelines tailored to other partner cities will be added in follow-up PRs.

Proposed approach

This PR mainly introduces two new files in the new docs folder. The README provides additional information concerning setting up an own, non-development, instance of the DECIDe application.

Furthermore, a Bamberg-specific docker compose override configuration was added. This configuration (partially) disables services that are not relevant for Bamberg and contains some template configuration for relevant services.

Furthermore, the primary README was updated with respect to

add links to used services where possible;
improved the documentation PDF harvesting pipeline (UC0.0);
slightly extended the documentation for UC0.1 to included the used services; and
documented UC2 smart search and revised the explanation to set up the smart search in a development stack.

How to test

Read all added documentation and assess whether it is factually correct and complete.
Add the Bamberg-specific docker compose override to your .env and ensure the stack can be properly started. Note, it is expected that some services do not function correctly due to placeholder values in their configuration.

Notes

In addition to the changes above, this PR also slightly simplifies the docker-compose configuration:

Merged smart-search.yml into search.yml as the frontend-smart-search configured in the former relates to the services configured in the latter.
Moved the configuration for the report-generation service into base-compose.yml to reduce the number of configuration files.

Related tickets

LBRON-1457

mirdono

Added some issues resulting from feedback via rocket.chat. (Along with one that caught my eye while adding these comments.)

mirdono · 2026-05-19T12:35:11Z

+| [Policy impact report](https://github.com/lblod/frontend-decide-policy-impact-report)                         | `policy-impact-report` |
+
+
+### Outsource LLM to the cloud


Issue: Clarify the need to obtain API keys for external services and how they are to be configured.

As part of LBRON-1423 the API keys will become environment variables to be configured in a non-versioned override file. This would be similar as the entity-linking configuration in the added example override.

Furthermore, it is probably best to emphasise these API keys are configured into a local docker-compose.override.yml instead of the versioned example override.

Updated the example override entry for named-entity-recognition based on #43

Updated the example override entry for pdf-content based on #24

mirdono · 2026-05-19T12:35:11Z

+For each service `A` that was added or updated (version bump or changed environment variables), do `docker compose up [-d] A`. For each service `B` for which their configuration was updated in the `../config/B` folder, do a `docker compose restart B`. Note, that `up` on its own does **not** cause a service to update its configuration.
+
+
+## Service configuration


Issue: Add a section for the ollama service.

The ollama service should pull in the appropriate LLMs, as described in #55. While the general README mentions this for the smart search setup it is currently not documented this is needed for other use cases as well.

i flagged this with pedro and joachim, the service should have ollama load the models on startup if they aren't available yet in ollama on disk and crash if that fails. Running manual pulls by drc execing seems crazy

mirdono · 2026-05-19T12:38:20Z

Issue: Document municipality-linker service.

In #99 a municipality-linker service was added. Check whether this requires further configuration and/or explanation in the context of this PR.

mirdono · 2026-05-21T08:48:25Z

Remark: Add documentation/pointer concerning task/job data model.

The pipelines with their jobs and tasks are central to the application but are not yet explicitly explained here. This came up in the project's get-together today.

mirdono · 2026-05-22T10:59:56Z

Issue: Document municipality-linker service.

In #99 a municipality-linker service was added. Check whether this requires further configuration and/or explanation in the context of this PR.

This service works as is, no partner-specific configuration needed.

mirdono · 2026-05-22T12:34:46Z

Remark: Add documentation/pointer concerning task/job data model.

The pipelines with their jobs and tasks are central to the application but are not yet explicitly explained here. This came up in the project's get-together today.

Added a short background section in the UC0.0 section. This very shortly introduces the essentials of the pipelines and provides a link to the more elaborate pipeline write up.

Our `docker-compose.dev.yml` does *not* publish the triplestore's port. Can be added to override if needed.

Add section documenting workaround for harvesting PDFs from Bamberg's web portal.

Document how user accounts for the pipeline dashboard can be added and disabled. This allows partners to manage their own users if they want to instead of only using the example test user.

mirdono · 2026-05-28T12:19:26Z

As discussed on standup of 28 May 2026, merged without explicit review as we want to get it out to the partners.

mirdono added the documentation Improvements or additions to documentation label May 18, 2026

mirdono self-assigned this May 18, 2026

mirdono force-pushed the chore/document-app-setup branch from da9a33d to 28c9eee Compare May 18, 2026 14:37

mirdono commented May 19, 2026

View reviewed changes

Rahien reviewed May 21, 2026

View reviewed changes

Comment thread docs/README.md

Rahien reviewed May 21, 2026

View reviewed changes

Comment thread docs/README.md Outdated

mirdono force-pushed the chore/document-app-setup branch from 166aa84 to 35f26e5 Compare May 22, 2026 12:33

mirdono mentioned this pull request May 26, 2026

chore: document application setup for Freiburg #108

Merged

mirdono force-pushed the chore/document-app-setup branch 2 times, most recently from bd15f83 to 353ad03 Compare May 27, 2026 12:16

mirdono added 16 commits May 28, 2026 14:13

chore: use consistent language for code blocks

777decc

chore(doc): remove incorrect comment concerning docker dev config

afe79c8

Our `docker-compose.dev.yml` does *not* publish the triplestore's port. Can be added to override if needed.

chore(doc): use links to for external resources

b3d4977

chore(doc): description of PDF pipeline

c5109f7

chore(doc): add explicit TODO to clarify sections will be written

d527c15

chore(doc): add short entry on policy impact report

65f2987

chore(doc): partner README placeholder

0180698

chore(doc): server requirements in partner README

b85cee6

chore(doc): short entry on updating application

cf5b019

chore(doc): partner-specific configuration entry

02ce639

chore(drc): docker override configuration for Bamberg

5f68590

chore(doc,drc): PDF harvesting for Bamberg

4d78106

Add section documenting workaround for harvesting PDFs from Bamberg's web portal.

chore(embedding): correct comment for set cron_schedule

6237a8a

chore(doc): revise section on smart search setup

8867a15

chore(doc): add explanation to configure external LLMs

4091da0

chore(doc): document server setup wrt identifier and dispatcher

d448ae6

mirdono added 21 commits May 28, 2026 14:13

chore(doc): account management for pipeline dashboard

49245c3

Document how user accounts for the pipeline dashboard can be added and disabled. This allows partners to manage their own users if they want to instead of only using the example test user.

chore(doc): remove lingering diff lines

a7a5b1b

chore(doc): add reference to partner-specific configurations

338142f

fix(doc): put general overwrite file last in .env example

47c38d0

chore(doc): improved documentation on using external LLM providers

ec9a695

chore(doc): add some background information for the pipelines

2d764b9

chore(doc): remove VC section placeholder

c26be5f

chore(doc,drc): add segmentation API key for pdf-content service

16df169

chore(drc): placholder for configuring an API key codelist-labeling

659c19e

chore(drc): remove unused volume for oparl-to-eli service

7a6af83

chore(doc): link to used services in OParl description

cb0a30b

chore(doc): typo

c64ddc4

chore(doc,drc): drc override configuration for Freiburg

a9cc64b

chore(doc): describe UC1

928c83d

chore(doc): use correct URI for SDG concept scheme

02ad884

chore(doc): data harvesting example Freiburg

e7e261e

chore(doc,drc): drc overwrite configuration for Ghent

595699a

chore(doc): document OSLO harvesting for Ghent

4839216

chore(doc): add warnings for configuration of API keys

84e63d9

chore(doc,drc): add warning for API key configuration

6432389

chore(doc,drc): add warning for API key configuration

e292eb7

mirdono force-pushed the chore/document-app-setup branch from 2098bc1 to e292eb7 Compare May 28, 2026 12:14

mirdono merged commit 9109184 into development May 28, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: document application setup (for partners)#101

chore: document application setup (for partners)#101
mirdono merged 37 commits into
developmentfrom
chore/document-app-setup

mirdono commented May 18, 2026

Uh oh!

mirdono left a comment

Uh oh!

Uh oh!

mirdono May 19, 2026

Uh oh!

mirdono May 22, 2026

Uh oh!

mirdono May 26, 2026

Uh oh!

mirdono May 19, 2026

Uh oh!

Rahien May 21, 2026

Uh oh!

mirdono commented May 19, 2026

Uh oh!

mirdono commented May 21, 2026

Uh oh!

Uh oh!

Uh oh!

mirdono commented May 22, 2026

Uh oh!

mirdono commented May 22, 2026

Uh oh!

mirdono commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		\| [Policy impact report](https://github.com/lblod/frontend-decide-policy-impact-report) \| `policy-impact-report` \|


		### Outsource LLM to the cloud

		For each service `A` that was added or updated (version bump or changed environment variables), do `docker compose up [-d] A`. For each service `B` for which their configuration was updated in the `../config/B` folder, do a `docker compose restart B`. Note, that `up` on its own does not cause a service to update its configuration.


		## Service configuration

Conversation

mirdono commented May 18, 2026

Proposed approach

How to test

Notes

Related tickets

Uh oh!

mirdono left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mirdono May 19, 2026

Choose a reason for hiding this comment

Uh oh!

mirdono May 22, 2026

Choose a reason for hiding this comment

Uh oh!

mirdono May 26, 2026

Choose a reason for hiding this comment

Uh oh!

mirdono May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Rahien May 21, 2026

Choose a reason for hiding this comment

Uh oh!

mirdono commented May 19, 2026

Uh oh!

mirdono commented May 21, 2026

Uh oh!

Uh oh!

Uh oh!

mirdono commented May 22, 2026

Uh oh!

mirdono commented May 22, 2026

Uh oh!

mirdono commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants