Add OCI container extractor by johnspade · Pull Request #81 · oddlama/nix-topology

johnspade · 2025-06-18T13:39:27Z

I deploy services as OCI containers on NixOS, so I wanted to create an extractor for virtualisation.oci-containers.containers. I had to do a little refactoring and extract the service registry so that the service extractors could share the service names and icons.

It works by matching the virtualisation.oci-containers.containers.<name>.image option with a list of known service container repository references (mostly official ones), e.g. jellyfin/jellyfin and linuxserver/jellyfin for Jellyfin.

Users can define custom functions to extract info and details from their container configurations, as well as override and update the service registry.

johnspade · 2025-06-18T13:42:09Z

+  in
+    mkIf (specNix != null && specNix.path != []) (
+      let
+        cfg = attrByPath specNix.path {} config;


Match the NixOS services by the option path

johnspade · 2025-06-18T13:43:17Z

            # The config should only be applied on the toplevel topology module,
            # not for each nixos node.
            config = {};
+            config.topology.serviceRegistry = serviceDefs;


Not sure about this line but it was the only way I could make it to work (I needed to expose the service registry to the NixOS configurations)

johnspade · 2025-06-18T13:44:06Z

+  };
+in
+  f {
+    options.serviceRegistry = mkOption {


Expose the service registry as an option (for overriding and customizations)

johnspade · 2025-06-18T13:45:20Z

+          map (svc: {inherit node svc;}) visible
+      ) (attrValues config.nodes);
+
+      # Deduplicate services by serviceId in overview


In the (supposedly rare) case when the same service deployed both as a container and a NixOS service display it only once in the overview

johnspade · 2025-06-18T13:46:43Z

+    repoLower = strings.toLower repo;
+  in
+    canon == repoLower || strings.hasSuffix ("/" + repoLower) canon;
+  matchesRepos = img: repos: builtins.any (suffixMatch img) repos;


Match the containerized services by the image reference

When I run this branch on my infrastructure it fails:

trace: oci-container extractor: UNMATCHED containers → shlink (shlinkio/shlink@sha256:1a697baca56ab8821783e0ce53eb4fb22e51bb66749ec50581adc0cb6d031d7a), slink (anirdev/slink@sha256:98b9442696f0a8cbc92f0447f54fa4bad227af5dcfd6680545fedab2ed28ddd9) trace: oci-container extractor: UNMATCHED containers → koillection (koillection/koillection@sha256:bb8ad2b6891441d8ec5c3169b684b71574f3bb3e9afb345bad2f91d833d60340)

and then later

error: attribute 'BaseUrl' missing at /nix/store/0djp82053nsd8pfmiwywmdhr9nbj48z8-source/nixos/builtin-service-defs.nix:999:51: 998| enabled = cfg: cfg.enable or false; 999| infoFn = cfg: mkIf (cfg.settings ? BaseUrl) cfg.settings.BaseUrl; | ^ 1000| detailsFn =

Given, I have not looked into how I can configure this, I simply ran it on my infra as is, so I might be missing something here.

Also tried adding to the service registry, e.g. for koillection: topology.serviceRegistry.koillection.oci.repos = [ “koillection” ];; while that makes the UNMATCHED disappear, it does not fix the above BaseUrl error

The BaseUrl error should be fixed now.

Also tried adding to the service registry, e.g. for koillection: topology.serviceRegistry.koillection.oci.repos = [ “koillection” ];

Yes, this is the intended way to match custom services.

johnspade · 2025-06-18T13:47:28Z

+      builtins.trace
+      ("oci-container extractor: UNMATCHED containers → "
+        + (concatStringsSep ", "
+          (map (c: "${c._name} (${c.image})") unmatched)))


Output the unmatched containers

Swarsel

Basically comments on what I encountered when trying to quickly run this on my config without looking at all into the specific configurations provided, so it might be I am doing something wrong

Swarsel · 2026-02-03T13:41:53Z

+    repoLower = strings.toLower repo;
+  in
+    canon == repoLower || strings.hasSuffix ("/" + repoLower) canon;
+  matchesRepos = img: repos: builtins.any (suffixMatch img) repos;


When I run this branch on my infrastructure it fails:

trace: oci-container extractor: UNMATCHED containers → shlink (shlinkio/shlink@sha256:1a697baca56ab8821783e0ce53eb4fb22e51bb66749ec50581adc0cb6d031d7a), slink (anirdev/slink@sha256:98b9442696f0a8cbc92f0447f54fa4bad227af5dcfd6680545fedab2ed28ddd9) trace: oci-container extractor: UNMATCHED containers → koillection (koillection/koillection@sha256:bb8ad2b6891441d8ec5c3169b684b71574f3bb3e9afb345bad2f91d833d60340)

and then later

error: attribute 'BaseUrl' missing at /nix/store/0djp82053nsd8pfmiwywmdhr9nbj48z8-source/nixos/builtin-service-defs.nix:999:51: 998| enabled = cfg: cfg.enable or false; 999| infoFn = cfg: mkIf (cfg.settings ? BaseUrl) cfg.settings.BaseUrl; | ^ 1000| detailsFn =

Given, I have not looked into how I can configure this, I simply ran it on my infra as is, so I might be missing something here.

Also tried adding to the service registry, e.g. for koillection: topology.serviceRegistry.koillection.oci.repos = [ “koillection” ];; while that makes the UNMATCHED disappear, it does not fix the above BaseUrl error

Swarsel · 2026-02-03T13:50:31Z

Currently this fails to build using nix build <flake>#docs because flake-utils is not a flake input. I would simply omit using it here

Thanks, omited it, it was a leftover from before flake-utils were removed from the project

Swarsel · 2026-02-03T13:51:26Z

+    };
+  };
+
+  config.topology.self = mkIf config.topology.extractors.oci-container.enable {


Currently, this renders as such (this is the added example):

Might be subjective, but I think it would be cool if we would render the containers as separate nodes (as in #126)

Could you clarify what's your reasoning for this? In my mind most containers will provide a single service, so they are rendered the same way as NixOS services, inside the parent host.

Swarsel · 2026-02-03T14:51:53Z

+    oci = {
+      repos = [ "forgejo/forgejo" ];
+    };
+  };


Now my config fails to build with error: A definition for option topology.nodes.summers-forgejo.services.forgejo.details.name is not of type submodule. [...].

At this point it seems likely that other services also have problems? I am not sure how you generated these service definitions, but the approach might need another look

Thanks for your review and recommendations! I adapted info/details functions from the existing list of services, but obviously some of the options are out of date and I need to be much more defensive in defining these functions so things don't blow up. I'll go through them, update the option names and add checks for nulls/non-existent names.

The current services on main should be working for the most part (at least I can vouch for forgejo)

Ok, I added a test flake config to check the successful evaluation of each service definition. forgejo/gitea were indeed adapted a bit inaccurately, but now everything should work (I hope).

Sorry this kinda flew under my radar; I will try to check this out again tomorrow or so

johnspade commented Jun 18, 2025

View reviewed changes

johnspade marked this pull request as ready for review June 18, 2025 13:48

Swarsel mentioned this pull request Jan 26, 2026

feat(extractors): Add support for oci-containers #126

Open

johnspade added 2 commits February 3, 2026 03:21

feat(extractors/oci-container): Add OCI container extractor

3d45052

Add new services

066dadc

johnspade force-pushed the feat/oci-extractor branch from 75f8e34 to 066dadc Compare February 3, 2026 11:59

Swarsel reviewed Feb 3, 2026

View reviewed changes

Format files

9618fd9

Swarsel reviewed Feb 3, 2026

View reviewed changes

johnspade added 3 commits February 4, 2026 01:46

Fix forgejo/gitea details

573ef9b

Add service definition tests

7df4845

Run service definition tests with nix flake check

74ddc6d

johnspade mentioned this pull request Feb 19, 2026

Decouple service registry from extractors #128

Open

Uh oh!

Conversation

johnspade commented Jun 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Swarsel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants