Rethink where app-integration config lives: combine.yml, alaconnect.yml, or config-sets? #12

New Issue

2026-08-25T13:10:24Z

dannygroenewegen commented

2026-08-25 13:10:24 +00:00

alakazam currently reads app-to-app integration config from a single combine.yml bundled in the alakazam repo itself.

The README already anticipates moving this out: "In future it should be split into the recipes repositories and maintained by the recipe maintainer. We started to move each app entry as alaconnect.yml into the respective repositories." Some (or all?) of combine.yml has been put in recipes alaconnect.yml, but alakazam's code doesn't read it yet. I want to make this work, but first want to check whether alaconnect.yml is still the direction we want.

It makes sense to me that a recipe owns the functionality for its own role in an integration, e.g. an abra.sh function on Authentik to create an OIDC client, and one on Nextcloud to connect to an OIDC provider. But the decision of what to configure/run when both Authentik and Nextcloud are in the same instance is a property of the pair, not of either recipe alone. Putting it in alaconnect.yml means splitting one integration's config across two recipe repos, which makes it harder to see the whole picture in one place.

Since we now have config-sets (config-sets.yml, activated per instance/group via CONFIG-SETS), that mechanism could cover this too: a config-set named combine-authentik-nextcloud, applied automatically when both apps are present in an instance instead of needing manual activation.

Possible paths forward:

Read combine.yml from the alakazam root path (in addition to, or instead of, the repo's own copy), keeping the repo's version as a shared catalogue of integrations.
Have alakazam read integrations from each recipe's alaconnect.yml, following the plan from the readme.
Keep integrations out of recipes entirely: introduce a toolshed/alakazam-configsets repo supporting multiple integration sets (e.g. authentik-integrations.yml, rauthy-integrations.yml), and update alakazam to auto-apply combine-<app1>-<app2> config-sets when both apps are part of an instance. alakazam could optionally clone toolshed/alakazam-configsets into the root path and merge it with the local config-sets.yml.

My preference: option 3. Using config-sets with a combine-<app1>-<app2> naming convention keeps a full integration readable in one place, and a shared config-sets repo lets integrations be reused/distributed the same way recipes are, without spreading integration logic across multiple recipe repos.

@moritz @simon Looking for feedback on whether this direction makes sense. If it does, I could work on implementing it.

alakazam currently reads app-to-app integration config from a single `combine.yml` bundled in the alakazam repo itself. The README already anticipates moving this out: _"In future it should be split into the recipes repositories and maintained by the recipe maintainer. We started to move each app entry as alaconnect.yml into the respective repositories."_ Some (or all?) of `combine.yml` has been put in recipes `alaconnect.yml`, but alakazam's code doesn't read it yet. I want to make this work, but first want to check whether alaconnect.yml is still the direction we want. It makes sense to me that a recipe owns the functionality for its own role in an integration, e.g. an abra.sh function on Authentik to create an OIDC client, and one on Nextcloud to connect to an OIDC provider. But the decision of what to configure/run when both Authentik and Nextcloud are in the same instance is a property of the pair, not of either recipe alone. Putting it in alaconnect.yml means splitting one integration's config across two recipe repos, which makes it harder to see the whole picture in one place. Since we now have config-sets (`config-sets.yml`, activated per instance/group via `CONFIG-SETS`), that mechanism could cover this too: a config-set named `combine-authentik-nextcloud`, applied automatically when both apps are present in an instance instead of needing manual activation. Possible paths forward: 1. Read `combine.yml` from the alakazam root path (in addition to, or instead of, the repo's own copy), keeping the repo's version as a shared catalogue of integrations. 2. Have alakazam read integrations from each recipe's `alaconnect.yml`, following the plan from the readme. 3. Keep integrations out of recipes entirely: introduce a `toolshed/alakazam-configsets` repo supporting multiple integration sets (e.g. `authentik-integrations.yml`, `rauthy-integrations.yml`), and update alakazam to auto-apply `combine-<app1>-<app2>` config-sets when both apps are part of an instance. alakazam could optionally clone `toolshed/alakazam-configsets` into the root path and merge it with the local `config-sets.yml`. My preference: option 3. Using config-sets with a `combine-<app1>-<app2>` naming convention keeps a full integration readable in one place, and a shared config-sets repo lets integrations be reused/distributed the same way recipes are, without spreading integration logic across multiple recipe repos. @moritz @simon Looking for feedback on whether this direction makes sense. If it does, I could work on implementing it.

moritz commented

2026-08-31 11:41:47 +00:00

Read combine.yml from the alakazam root path (in addition to, or instead of, the repo's own copy), keeping the repo's version as a shared catalogue of integrations.

I think this is the way we should go. We would keep our combine.yml public inside https://git.local-it.org/local-it/kolli-config. This combine.yml will be tested with the versions pinned in the repository.

Problems of the alternatives:

Keep it in inside this repo: The combine.yml can not reference any versions and sometimes some integrations only work with specific versions or break with other versions, further it can not be customized without changes inside this repo.
Having it in each recipe's alaconnect.yml: as you stated above the configuration that belongs together would be split across multiple recipes. Further the recipe versions, for which this configurations works is pinned per recipe, but not together.
using configsets would clutter the instance config with duplicated configurations, which can be retrieved implicitly with the logic the combine.yml uses. Further here is the relation to the recipe versions missing as in 1.)

How should we than name it?

combine.yml
alaconnect.yml
`alaka-connect.yml
alaka-integrate.yml
...

> Read `combine.yml` from the alakazam root path (in addition to, or instead of, the repo's own copy), keeping the repo's version as a shared catalogue of integrations. I think this is the way we should go. We would keep our combine.yml public inside https://git.local-it.org/local-it/kolli-config. This combine.yml will be tested with the versions pinned in the repository. Problems of the alternatives: 1. Keep it in inside this repo: The combine.yml can not reference any versions and sometimes some integrations only work with specific versions or break with other versions, further it can not be customized without changes inside this repo. 2. Having it in each recipe's alaconnect.yml: as you stated above the configuration that belongs together would be split across multiple recipes. Further the recipe versions, for which this configurations works is pinned per recipe, but not together. 3. using configsets would clutter the instance config with duplicated configurations, which can be retrieved implicitly with the logic the `combine.yml` uses. Further here is the relation to the recipe versions missing as in 1.) How should we than name it? - `combine.yml` - `alaconnect.yml` - `alaka-connect.yml - `alaka-integrate.yml` - ...

dannygroenewegen commented

2026-08-31 15:03:58 +00:00

Good point, the integration config should indeed be alongside alaka-versions.yml. So that puts it somewhere in root_path. I would also want to share this publicly. Quick side question on the public/private split: with kolli-config public and a private infra repo containing the instance files, the public alaka-*.yml files need to be in a parent folder of the instance configs. How do you work with this? Private repo cloned within the public repo clone, or symlinking all files? Or is there another smart trick that I'm missing?

The reason I proposed using config-sets: I think doing both config-sets and integrations with the same file layout simplifies the setup. Both in code and in reading the config files.

Currently, in combine.yml there are 100+ lines to scroll through to read both sides of an integration.

authentik:
    nextcloud:
        uncomment:
            - compose.nextcloud.yml
         ...
     <100+ lines of other apps>
nextcloud:
    authentik:
        uncomment:
            - compose.authentik.yml
        ...

And with "would clutter the instance config with duplicated configurations" you mean that config-sets have to be enabled for every instance/group, right? But that is something that can be changed. We could add e.g., an auto-enable key to config-sets:

config-sets.yml:

integrate-authentik-nextcloud:
    auto-enable: true
    authentik:
        uncomment:
            - compose.authentik.yml
        ...
    nextcloud:
        uncomment:
            - compose.nextcloud.yml
         ...

Then whenever a config-set has auto-enable set to true, this config set will be automatically applied when all apps from a config set are part of an instance.

With this, we get one less structurally different file and both sides of an integration right after each other.

Good point, the integration config should indeed be alongside alaka-versions.yml. So that puts it somewhere in root_path. I would also want to share this publicly. Quick side question on the public/private split: with [kolli-config](https://git.local-it.org/local-it/kolli-config) public and a private infra repo containing the instance files, the public `alaka-*.yml` files need to be in a parent folder of the instance configs. How do you work with this? Private repo cloned within the public repo clone, or symlinking all files? Or is there another smart trick that I'm missing? The reason I proposed using config-sets: I think doing both config-sets and integrations with the same file layout simplifies the setup. Both in code and in reading the config files. Currently, in `combine.yml` there are 100+ lines to scroll through to read both sides of an integration. ``` authentik: nextcloud: uncomment: - compose.nextcloud.yml ... <100+ lines of other apps> nextcloud: authentik: uncomment: - compose.authentik.yml ... ``` And with _"would clutter the instance config with duplicated configurations"_ you mean that config-sets have to be enabled for every instance/group, right? But that is something that can be changed. We could add e.g., an `auto-enable` key to config-sets: `config-sets.yml`: ``` integrate-authentik-nextcloud: auto-enable: true authentik: uncomment: - compose.authentik.yml ... nextcloud: uncomment: - compose.nextcloud.yml ... ``` Then whenever a config-set has auto-enable set to true, this config set will be automatically applied when all apps from a config set are part of an instance. With this, we get one less structurally different file and both sides of an integration right after each other.

moritz commented

2026-08-31 16:53:40 +00:00

We're symlinking the files inside kolli-config into our root_path.

Ok, now I understand your config-set idea I overlooked that you wrote

update alakazam to auto-apply combine-<app1>-<app2> config-sets when both apps are part of an instance

I really like the idea of grouping the combine configurations inside the file.
But I would like to separate different concerns, else the combine-set.yml would get very large.
Either we have a combine.yml that works like the config-set.yml with auto-enable: true for all entries or we have different config-set-*.yml files that can be merged like the alaka-*.yml files.
Then there could be a config-set-combine.yml for all apps or a config-set-authentik-integrations.yml only for the authentik integrations.

We're symlinking the files inside [kolli-config](https://git.local-it.org/local-it/kolli-config) into our root_path. Ok, now I understand your config-set idea I overlooked that you wrote > update alakazam to auto-apply `combine-<app1>-<app2>` config-sets when both apps are part of an instance I really like the idea of grouping the combine configurations inside the file. But I would like to separate different concerns, else the `combine-set.yml` would get very large. Either we have a `combine.yml` that works like the `config-set.yml` with `auto-enable: true` for all entries or we have different `config-set-*.yml` files that can be merged like the `alaka-*.yml` files. Then there could be a `config-set-combine.yml` for all apps or a `config-set-authentik-integrations.yml` only for the authentik integrations.

dannygroenewegen commented

2026-08-31 18:39:16 +00:00

Either we have a combine.yml that works like the config-set.yml with auto-enable: true for all entries or we have different config-set-*.yml files that can be merged like the alaka-*.yml files.
Then there could be a config-set-combine.yml for all apps or a config-set-authentik-integrations.yml only for the authentik integrations.

I also think multiple config-set-*.yml would be helpful to separate. I'll make a PR so we can review the details. I'll look at what works when writing it. Maybe some option in config-set-authentik-integrations.yml to enable everything in it, or based on filenameconfig-set-enabled-authentik-integrations.yml.

> Either we have a `combine.yml` that works like the `config-set.yml` with `auto-enable: true` for all entries or we have different `config-set-*.yml` files that can be merged like the `alaka-*.yml` files. > Then there could be a `config-set-combine.yml` for all apps or a `config-set-authentik-integrations.yml` only for the authentik integrations. I also think multiple `config-set-*.yml` would be helpful to separate. I'll make a PR so we can review the details. I'll look at what works when writing it. Maybe some option in `config-set-authentik-integrations.yml` to enable everything in it, or based on filename`config-set-enabled-authentik-integrations.yml`.

👍 1

moritz referenced this issue

2026-09-09 21:20:27 +00:00

feat(config)!: replace combine.yml with auto-applying config-sets #12 #14

moritz commented

2026-09-09 21:25:34 +00:00

We started to use the alakazam image in our pipeline. Because the combine.yml is baked into the image and each change to the combine.yml requires a new alakazam release this issue got high prio. Therefore I already created a PR to solve this: #14
Further I tagged the PR with version 2.0.0 (major release because of the breaking change) to already build the image and test it.

We started to use the alakazam image in our pipeline. Because the combine.yml is baked into the image and each change to the combine.yml requires a new alakazam release this issue got high prio. Therefore I already created a PR to solve this: https://git.coopcloud.tech/toolshed/alakazam/pulls/14 Further I tagged the PR with version 2.0.0 (major release because of the breaking change) to already build the image and test it.

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: toolshed/alakazam#12

Rethink where app-integration config lives: combine.yml, alaconnect.yml, or config-sets? #12

Rethink where app-integration config lives: `combine.yml`, `alaconnect.yml`, or config-sets? #12