draft types

see Fediversity/Fediversity#395 (comment)

Reviewed-on: Fediversity/Fediversity#396
Reviewed-by: Valentin Gagarin <valentin.gagarin@tweag.io>
Co-authored-by: Kiara Grouwstra <kiara@procolix.eu>
Co-committed-by: Kiara Grouwstra <kiara@procolix.eu>

.forgejo/workflows/ci.yaml

@@ -15,6 +15,12 @@ jobs:
       - uses: actions/checkout@v4
       - run: nix-build -A tests
 
+  check-data-model:
+    runs-on: native
+    steps:
+      - uses: actions/checkout@v4
+      - run: nix-shell --run 'nix-unit ./test.nix'
+
   check-peertube:
     runs-on: native
     steps:
@@ -38,3 +44,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - run: nix build .#checks.x86_64-linux.deployment-cli -L
+
+  check-deployment-panel:
+    runs-on: native
+    steps:
+      - uses: actions/checkout@v4
+      - run: nix build .#checks.x86_64-linux.deployment-panel -L

README.md

@@ -154,6 +154,3 @@ details as to what they are for. As an overview:
 
 - [`services/`](./services) contains our effort to make Fediverse applications
   work seemlessly together in our specific setting.
-
-- [`website/`](./website) contains the framework and the content of [the
-  Fediversity website](https://fediversity.eu/)

default.nix

@@ -41,6 +41,23 @@ in
   shell = pkgs.mkShellNoCC {
     inherit (pre-commit-check) shellHook;
     buildInputs = pre-commit-check.enabledPackages;
+    packages =
+      let
+        test-loop = pkgs.writeShellApplication {
+          name = "test-loop";
+          runtimeInputs = [
+            pkgs.watchexec
+            pkgs.nix-unit
+          ];
+          text = ''
+            watchexec -w ${builtins.toString ./.} -- nix-unit ${builtins.toString ./test.nix} "$@"
+          '';
+        };
+      in
+      [
+        pkgs.nix-unit
+        test-loop
+      ];
   };
 
   tests = {

deployment/README.md

@@ -3,6 +3,13 @@
 This directory contains work to generate a full Fediversity deployment from a minimal configuration.
 This is different from [`../services/`](../services) that focuses on one machine, providing a polished and unified interface to different Fediverse services.
 
+## Data model
+
+The core piece of the project is the [Fediversity data model](./data-model.nix), which describes all entities and their interactions.
+
+What can be done with it is exemplified in the [evaluation tests](./data-model-test.nix).
+Run `test-loop` in the development environment when hacking on the data model or adding tests.
+
 ## Checks
 
 There are three levels of deployment checks: `basic`, `cli`, `panel`.
@@ -109,8 +116,8 @@ flowchart LR
   target_machines -->|get certs| acme
 ```
 
-### [WIP] Service deployment check from the panel
+### Service deployment check from the FediPanel
 
-This is a full deployment check running the panel on the deployer machine, deploying some services through the panel and checking that they are indeed on the target machines, then cleans them up and checks whether that works, too.
+This is a full deployment check running the [FediPanel](../panel) on the deployer machine, deploying some services through it and checking that they are indeed on the target machines, then cleans them up and checks whether that works, too.
 
-It builds upon the basic and CLI deployment checks.
+It builds upon the basic and CLI deployment checks, the only difference being that `deployer` runs NixOps4 only indirectly via the panel, and the `client` node is the one that triggers the deployment via a browser, the way a human would.

deployment/application.nix

@@ -0,0 +1,83 @@
+{
+  lib,
+  ...
+}:
+let
+  inherit (lib) types mkOption;
+in
+with types;
+{
+  options = {
+    runtime-environments = mkOption {
+      type = attrsOf (attrTag {
+        nixos = mkOption {
+          type = submodule {
+            options = {
+              module = mkOption {
+                description = "The NixOS module of the run-time environment";
+                type = deferredModule;
+              };
+            };
+          };
+        };
+      });
+    };
+    applications = mkOption {
+      description = "Collection of NixOS modules, each implementing a Fediversity application";
+      example.hello = {
+        enable = true;
+        module = {pkgs, ...}: {
+          environment.systemPackages = [ pkgs.hello ];
+        };
+      };
+      type = attrsOf (submoduleWith {
+        description = "A Fediversity application";
+        modules = [
+          {
+            options = {
+              module = mkOption {
+                description = "The NixOS module to compose into an operator's configuration";
+                type = deferredModule;
+              };
+              components = mkOption {
+                type = with types; attrsOf (attrTag {
+                  file-system-state = mkOption {
+                    desciption = "files stored by the application";
+                    type = with types; attrsOf (submodule {
+                      options.minSize = types.bytes;
+                    });
+                    database-state = mkOption {
+                      desciption = "state stored in databases by the application";
+                      type =
+                        with types;
+                        attrsOf (submodule {
+                          postgresql = mkOption {
+                            desciption = "state stored in PostgreSQL by the application";
+                            type =
+                              with types;
+                              attrsOf (submodule {
+                                options = {
+                                };
+                              });
+                          };
+                          key-val = mkOption {
+                            desciption = "state stored in a key-value store by the application";
+                            type =
+                              with types;
+                              attrsOf (submodule {
+                                options = {
+                                };
+                              });
+                          };
+                        });
+                    };
+                  };
+                });
+              };
+            };
+          }
+        ];
+      });
+    };
+  };
+}

deployment/check/cli/deployer.pub

@@ -1 +0,0 @@
-## This is a placeholder file. It will be overwritten by the test.

deployment/check/common/nixosTest.nix

@@ -119,7 +119,6 @@ in
       with subtest("Configure the deployer key"):
         deployer.succeed("""mkdir -p ~/.ssh && ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa""")
         deployer_key = deployer.succeed("cat ~/.ssh/id_rsa.pub").strip()
-        deployer.succeed(f"echo '{deployer_key}' > ${config.pathFromRoot}/deployer.pub")
         ${forConcat config.targetMachines (tm: ''
           ${tm}.succeed(f"mkdir -p /root/.ssh && echo '{deployer_key}' >> /root/.ssh/authorized_keys")
         '')}

deployment/check/panel/flake-part.nix

@@ -0,0 +1,91 @@
+{
+  self,
+  inputs,
+  lib,
+  ...
+}:
+
+let
+  inherit (builtins)
+    fromJSON
+    listToAttrs
+    ;
+
+  targetMachines = [
+    "garage"
+    "mastodon"
+    "peertube"
+    "pixelfed"
+  ];
+  pathToRoot = /. + (builtins.unsafeDiscardStringContext self);
+  pathFromRoot = ./.;
+  enableAcme = true;
+
+in
+{
+  perSystem =
+    { pkgs, ... }:
+    {
+      checks.deployment-panel = pkgs.testers.runNixOSTest {
+        imports = [
+          ../common/nixosTest.nix
+          ./nixosTest.nix
+        ];
+        _module.args.inputs = inputs;
+        inherit
+          targetMachines
+          pathToRoot
+          pathFromRoot
+          enableAcme
+          ;
+      };
+    };
+
+  nixops4Deployments =
+    let
+      makeTargetResource = nodeName: {
+        imports = [ ../common/targetResource.nix ];
+        _module.args.inputs = inputs;
+        inherit
+          nodeName
+          pathToRoot
+          pathFromRoot
+          enableAcme
+          ;
+      };
+
+      ## The deployment function - what we are here to test!
+      ##
+      ## TODO: Modularise `deployment/default.nix` to get rid of the nested
+      ## function calls.
+      makeTestDeployment =
+        args:
+        (import ../..)
+          {
+            inherit lib;
+            inherit (inputs) nixops4 nixops4-nixos;
+            fediversity = import ../../../services/fediversity;
+          }
+          (listToAttrs (
+            map (nodeName: {
+              name = "${nodeName}ConfigurationResource";
+              value = makeTargetResource nodeName;
+            }) targetMachines
+          ))
+          args;
+
+    in
+    {
+      check-deployment-panel = makeTestDeployment (
+        fromJSON (
+          let
+            env = builtins.getEnv "DEPLOYMENT";
+          in
+          if env == "" then
+            throw "The DEPLOYMENT environment needs to be set. You do not want to use this deployment unless in the `deployment-panel` NixOS test."
+          else
+            env
+        )
+      );
+    };
+}

deployment/check/panel/nixosTest.nix

@@ -0,0 +1,362 @@
+{
+  inputs,
+  lib,
+  hostPkgs,
+  config,
+  ...
+}:
+
+let
+  inherit (lib)
+    getExe
+    ;
+
+  ## Some places need a dummy file that will in fact never be used. We create
+  ## it here.
+  dummyFile = hostPkgs.writeText "dummy" "dummy";
+  panelPort = 8000;
+
+  panelUser = "test";
+  panelEmail = "test@test.com";
+  panelPassword = "ouiprdaaa43"; # panel's manager complains if too close to username or email
+
+  fediUser = "test";
+  fediEmail = "test@test.com";
+  fediPassword = "testtest";
+  fediName = "Testy McTestface";
+
+  toPythonBool = b: if b then "True" else "False";
+
+  interactWithPanel =
+    {
+      baseUri,
+      enableMastodon,
+      enablePeertube,
+      enablePixelfed,
+    }:
+    hostPkgs.writers.writePython3Bin "interact-with-panel"
+      {
+        libraries = with hostPkgs.python3Packages; [ selenium ];
+        flakeIgnore = [
+          "E302" # expected 2 blank lines, found 0
+          "E303" # too many blank lines
+          "E305" # expected 2 blank lines after end of function or class
+          "E501" # line too long (> 79 characters)
+          "E731" # do not assign lambda expression, use a def
+        ];
+      }
+      ''
+        from selenium import webdriver
+        from selenium.webdriver.common.by import By
+        from selenium.webdriver.firefox.options import Options
+        from selenium.webdriver.support.ui import WebDriverWait
+
+        print("Create and configure driver...")
+        options = Options()
+        options.add_argument("--headless")
+        options.binary_location = "${getExe hostPkgs.firefox-unwrapped}"
+        service = webdriver.FirefoxService(executable_path="${getExe hostPkgs.geckodriver}")
+        driver = webdriver.Firefox(options=options, service=service)
+        driver.set_window_size(1280, 960)
+        driver.implicitly_wait(360)
+        driver.command_executor.set_timeout(3600)
+
+        print("Open login page...")
+        driver.get("${baseUri}/login/")
+        print("Enter username...")
+        driver.find_element(By.XPATH, "//input[@name = 'username']").send_keys("${panelUser}")
+        print("Enter password...")
+        driver.find_element(By.XPATH, "//input[@name = 'password']").send_keys("${panelPassword}")
+        print("Click “Login” button...")
+        driver.find_element(By.XPATH, "//button[normalize-space() = 'Login']").click()
+
+        print("Open configuration page...")
+        driver.get("${baseUri}/configuration/")
+
+        # Helpers to actually set and not add or switch input values.
+        def input_set(elt, keys):
+            elt.clear()
+            elt.send_keys(keys)
+        def checkbox_set(elt, new_value):
+            if new_value != elt.is_selected():
+                elt.click()
+
+        print("Enable Fediversity...")
+        checkbox_set(driver.find_element(By.XPATH, "//input[@name = 'enable']"), True)
+
+        print("Fill in initialUser info...")
+        input_set(driver.find_element(By.XPATH, "//input[@name = 'initialUser.username']"), "${fediUser}")
+        input_set(driver.find_element(By.XPATH, "//input[@name = 'initialUser.password']"), "${fediPassword}")
+        input_set(driver.find_element(By.XPATH, "//input[@name = 'initialUser.email']"), "${fediEmail}")
+        input_set(driver.find_element(By.XPATH, "//input[@name = 'initialUser.displayName']"), "${fediName}")
+
+        print("Enable services...")
+        checkbox_set(driver.find_element(By.XPATH, "//input[@name = 'mastodon.enable']"), ${toPythonBool enableMastodon})
+        checkbox_set(driver.find_element(By.XPATH, "//input[@name = 'peertube.enable']"), ${toPythonBool enablePeertube})
+        checkbox_set(driver.find_element(By.XPATH, "//input[@name = 'pixelfed.enable']"), ${toPythonBool enablePixelfed})
+
+        print("Start deployment...")
+        driver.find_element(By.XPATH, "//button[@id = 'deploy-button']").click()
+
+        print("Wait for deployment status to show up...")
+        get_deployment_result = lambda d: d.find_element(By.XPATH, "//div[@id = 'deployment-result']//p")
+        WebDriverWait(driver, timeout=3660, poll_frequency=10).until(get_deployment_result)
+        deployment_result = get_deployment_result(driver).get_attribute('innerHTML')
+
+        print("Quit...")
+        driver.quit()
+
+        match deployment_result:
+            case 'Deployment Succeeded':
+                print("Deployment has succeeded; exiting normally")
+                exit(0)
+            case 'Deployment Failed':
+                print("Deployment has failed; exiting with return code `1`")
+                exit(1)
+            case _:
+                print(f"Unexpected deployment result: {deployment_result}; exiting with return code `2`")
+                exit(2)
+      '';
+
+in
+
+{
+  name = "deployment-panel";
+
+  ## The panel's module sets `nixpkgs.overlays` which clashes with
+  ## `pkgsReadOnly`. We disable it here.
+  node.pkgsReadOnly = false;
+
+  nodes.deployer =
+    { pkgs, ... }:
+    {
+      imports = [
+        (import ../../../panel { }).module
+      ];
+
+      ## FIXME: This should be in the common stuff.
+      security.acme = {
+        acceptTerms = true;
+        defaults.email = "test@test.com";
+        defaults.server = "https://acme.test/dir";
+      };
+      security.pki.certificateFiles = [
+        (import "${inputs.nixpkgs}/nixos/tests/common/acme/server/snakeoil-certs.nix").ca.cert
+      ];
+      networking.extraHosts = "${config.acmeNodeIP} acme.test";
+
+      services.panel = {
+        enable = true;
+        production = true;
+        domain = "deployer";
+        secrets = {
+          SECRET_KEY = dummyFile;
+        };
+        port = panelPort;
+        nixops4Package = inputs.nixops4.packages.${pkgs.system}.default;
+
+        deployment = {
+          flake = "/run/fedipanel/flake";
+          name = "check-deployment-panel";
+        };
+      };
+
+      environment.systemPackages = [ pkgs.expect ];
+
+      ## FIXME: The following dependencies are necessary but I do not
+      ## understand why they are not covered by the fake node.
+      system.extraDependencies = with pkgs; [
+        peertube
+        peertube.inputDerivation
+        gixy # a configuration checker for nginx
+        gixy.inputDerivation
+      ];
+
+      system.extraDependenciesFromModule = {
+        imports = [ ../../../services/fediversity ];
+        fediversity = {
+          domain = "fediversity.net"; # would write `dummy` but that would not type
+          garage.enable = true;
+          mastodon = {
+            enable = true;
+            s3AccessKeyFile = dummyFile;
+            s3SecretKeyFile = dummyFile;
+          };
+          peertube = {
+            enable = true;
+            secretsFile = dummyFile;
+            s3AccessKeyFile = dummyFile;
+            s3SecretKeyFile = dummyFile;
+          };
+          pixelfed = {
+            enable = true;
+            s3AccessKeyFile = dummyFile;
+            s3SecretKeyFile = dummyFile;
+          };
+          temp.cores = 1;
+          temp.initialUser = {
+            username = "dummy";
+            displayName = "dummy";
+            email = "dummy";
+            passwordFile = dummyFile;
+          };
+        };
+      };
+    };
+
+  nodes.client =
+    { pkgs, ... }:
+    {
+      environment.systemPackages = with pkgs; [
+        httpie
+        dnsutils # for `dig`
+        openssl
+        cacert
+        wget
+        python3
+        python3Packages.selenium
+        firefox-unwrapped
+        geckodriver
+      ];
+
+      security.pki.certificateFiles = [
+        config.nodes.acme.test-support.acme.caCert
+      ];
+      networking.extraHosts = "${config.acmeNodeIP} acme.test";
+    };
+
+  ## NOTE: The target machines may need more RAM than the default to handle
+  ## being deployed to, otherwise we get something like:
+  ##
+  ##     pixelfed # [  616.785499 ] sshd-session[1167]: Conection closed by 2001:db8:1::2 port 45004
+  ##     deployer # error: writing to file: No space left on device
+  ##     pixelfed # [  616.788538 ] sshd-session[1151]: pam_unix(sshd:session): session closed for user port
+  ##     pixelfed # [  616.793929 ] systemd-logind[719]: Session 4 logged out. Waiting for processes to exit.
+  ##     deployer # Error: Could not create resource
+  ##
+  ## These values have been trimmed down to the gigabyte.
+  nodes.mastodon.virtualisation.memorySize = 4 * 1024;
+  nodes.pixelfed.virtualisation.memorySize = 4 * 1024;
+  nodes.peertube.virtualisation.memorySize = 5 * 1024;
+
+  ## FIXME: The test of presence of the services are very simple: we only
+  ## check that there is a systemd service of the expected name on the
+  ## machine. This proves at least that NixOps4 did something, and we cannot
+  ## really do more for now because the services aren't actually working
+  ## properly, in particular because of DNS issues. We should fix the services
+  ## and check that they are working properly.
+
+  extraTestScript = ''
+    ## TODO: We want a nicer way to control where the FediPanel consumes its
+    ## flake, which can default to the store but could also be somewhere else if
+    ## someone wanted to change the code of the flake.
+    ##
+    with subtest("Give the panel access to the flake"):
+      deployer.succeed("mkdir /run/fedipanel /run/fedipanel/flake >&2")
+      deployer.succeed("cp -R . /run/fedipanel/flake >&2")
+      deployer.succeed("chown -R panel:panel /run/fedipanel >&2")
+
+    ## TODO: I want a programmatic way to provide an SSH key to the panel (and
+    ## therefore NixOps4). This should happen either in the Python code, but
+    ## maybe it is fair that that one picks up on the user's key? It could
+    ## also be in the Nix packaging.
+    ##
+    with subtest("Set up the panel's SSH keys"):
+      deployer.succeed("mkdir /home/panel/.ssh >&2")
+      deployer.succeed("cp -R /root/.ssh/* /home/panel/.ssh >&2")
+      deployer.succeed("chown -R panel:panel /home/panel/.ssh >&2")
+      deployer.succeed("chmod 600 /home/panel/.ssh/* >&2")
+
+    ## TODO: This is a hack to accept the root CA used by Pebble on the client
+    ## machine. Pebble randomizes everything, so the only way to get it is to
+    ## call the /roots/0 endpoint at runtime, leaving not much margin for a nice
+    ## Nixy way of adding the certificate. There is no way around it as this is
+    ## by design in Pebble, showing in fact that Pebble was not the appropriate
+    ## tool for our use and that nixpkgs does not in fact provide an easy way to
+    ## generate _usable_ certificates in NixOS tests. I suggest we merge this,
+    ## and track the task to set it up in a cleaner way. I would tackle this in
+    ## a subsequent PR, and hopefully even contribute this BetterWay(tm) to
+    ## nixpkgs. — Niols
+    ##
+    with subtest("Set up ACME root CA on client"):
+      client.succeed("""
+        cd /etc/ssl/certs
+        curl -o pebble-root-ca.pem https://acme.test:15000/roots/0
+        curl -o pebble-intermediate-ca.pem https://acme.test:15000/intermediates/0
+        { cat ca-bundle.crt
+          cat pebble-root-ca.pem
+          cat pebble-intermediate-ca.pem
+        } > new-ca-bundle.crt
+        rm ca-bundle.crt ca-certificates.crt
+        mv new-ca-bundle.crt ca-bundle.crt
+        ln -s ca-bundle.crt ca-certificates.crt
+      """)
+
+    ## TODO: I would hope for a more declarative way to add users. This should
+    ## be handled by the Nix packaging of the FediPanel. — Niols
+    ##
+    with subtest("Create panel user"):
+      deployer.succeed("""
+        expect -c '
+          spawn manage createsuperuser --username ${panelUser} --email ${panelEmail}
+          expect "Password: "; send "${panelPassword}\\n";
+          expect "Password (again): "; send "${panelPassword}\\n"
+          interact
+        ' >&2
+      """)
+
+    with subtest("Check the status of the services - there should be none"):
+      garage.fail("systemctl status garage.service")
+      mastodon.fail("systemctl status mastodon-web.service")
+      peertube.fail("systemctl status peertube.service")
+      pixelfed.fail("systemctl status phpfpm-pixelfed.service")
+
+    with subtest("Run deployment with no services enabled"):
+      client.succeed("${
+        interactWithPanel {
+          baseUri = "https://deployer";
+          enableMastodon = false;
+          enablePeertube = false;
+          enablePixelfed = false;
+        }
+      }/bin/interact-with-panel >&2")
+
+    with subtest("Check the status of the services - there should still be none"):
+      garage.fail("systemctl status garage.service")
+      mastodon.fail("systemctl status mastodon-web.service")
+      peertube.fail("systemctl status peertube.service")
+      pixelfed.fail("systemctl status phpfpm-pixelfed.service")
+
+    with subtest("Run deployment with Mastodon and Pixelfed enabled"):
+      client.succeed("${
+        interactWithPanel {
+          baseUri = "https://deployer";
+          enableMastodon = true;
+          enablePeertube = false;
+          enablePixelfed = true;
+        }
+      }/bin/interact-with-panel >&2")
+
+    with subtest("Check the status of the services - expecting Garage, Mastodon and Pixelfed"):
+      garage.succeed("systemctl status garage.service")
+      mastodon.succeed("systemctl status mastodon-web.service")
+      peertube.fail("systemctl status peertube.service")
+      pixelfed.succeed("systemctl status phpfpm-pixelfed.service")
+
+    with subtest("Run deployment with only Peertube enabled"):
+      client.succeed("${
+        interactWithPanel {
+          baseUri = "https://deployer";
+          enableMastodon = false;
+          enablePeertube = true;
+          enablePixelfed = false;
+        }
+      }/bin/interact-with-panel >&2")
+
+    with subtest("Check the status of the services - expecting Garage and Peertube"):
+      garage.succeed("systemctl status garage.service")
+      mastodon.fail("systemctl status mastodon-web.service")
+      peertube.succeed("systemctl status peertube.service")
+      pixelfed.fail("systemctl status phpfpm-pixelfed.service")
+  '';
+}

deployment/data-model-test.nix

@@ -0,0 +1,45 @@
+let
+  inherit (import ../default.nix { }) pkgs;
+  inherit (pkgs) lib;
+  eval =
+    module:
+    (lib.evalModules {
+      modules = [
+        module
+        ./data-model.nix
+      ];
+    }).config;
+in
+{
+  test-eval = {
+    expr =
+      let
+        example = eval {
+          runtime-environments.bar.nixos = {
+            module =
+              { ... }:
+              {
+                system.stateVersion = "25.05";
+              };
+          };
+          applications.foo = {
+            module =
+              { pkgs, ... }:
+              {
+                environment.systemPackages = [
+                  pkgs.hello
+                ];
+              };
+          };
+        };
+      in
+      {
+        has-runtime = lib.isAttrs example.runtime-environments.bar.nixos.module;
+        has-application = lib.isAttrs example.applications.foo.module;
+      };
+    expected = {
+      has-runtime = true;
+      has-application = true;
+    };
+  };
+}

deployment/data-model.nix

@@ -0,0 +1,43 @@
+{
+  lib,
+  ...
+}:
+let
+  inherit (lib) types mkOption;
+in
+with types;
+{
+  options = {
+    runtime-environments = mkOption {
+      description = "Collection of runtime environments into which applications can be deployed";
+      type = attrsOf (attrTag {
+        nixos = mkOption {
+          description = "A single NixOS machine";
+          type = submodule {
+            options = {
+              module = mkOption {
+                description = "The NixOS module describing the base configuration for that machine";
+                type = deferredModule;
+              };
+            };
+          };
+        };
+      });
+    };
+    applications = mkOption {
+      description = "Collection of Fediversity applications";
+      type = attrsOf (submoduleWith {
+        modules = [
+          {
+            options = {
+              module = mkOption {
+                description = "The NixOS module for that application, for configuring that application";
+                type = deferredModule;
+              };
+            };
+          }
+        ];
+      });
+    };
+  };
+}

deployment/default.nix

@@ -37,47 +37,19 @@ panelConfigNullable:
 
 let
   inherit (lib) mkIf;
-
-  ## The convertor from module options to JSON schema does not generate proper
-  ## JSON schema types, forcing us to use nullable fields for default values.
-  ## However, working with those fields in the deployment code is annoying (and
-  ## unusual for Nix programmers), so we sanitize the input here and add back
-  ## the default value by hand.
-  nonNull = x: v: if x == null then v else x;
-  panelConfig = {
-    domain = nonNull panelConfigNullable.domain "fediversity.net";
-    initialUser = nonNull panelConfigNullable.initialUser {
-      displayName = "Testy McTestface";
-      username = "test";
-      password = "testtest";
-      email = "test@test.com";
-    };
-    mastodon = nonNull panelConfigNullable.mastodon { enable = false; };
-    peertube = nonNull panelConfigNullable.peertube { enable = false; };
-    pixelfed = nonNull panelConfigNullable.pixelfed { enable = false; };
-  };
 in
 
 ## Regular arguments of a NixOps4 deployment module.
 { config, providers, ... }:
 
 let
-  cfg = config.deployment;
+  cfg = config.deployment.module;
 in
 {
-  options = {
-    deployment = lib.mkOption {
-      description = ''
-        Configuration to be deployed
-      '';
-      # XXX(@fricklerhandwerk):
-      #     misusing this will produce obscure errors that will be truncated by NixOps4
-      type = lib.types.submodule ./options.nix;
-      default = panelConfig;
-    };
-  };
+  imports = [
+    (import ./deployment.nix { inherit lib panelConfigNullable; })
+  ];
 
-  config = {
   providers = { inherit (nixops4.modules.nixops4Provider) local; };
 
   resources =
@@ -212,5 +184,4 @@ in
         }
       );
     };
-  };
 }

deployment/deployment.nix

@@ -0,0 +1,50 @@
+{
+  lib,
+  panelConfigNullable,
+  ...
+}:
+let
+  inherit (lib) types mkOption;
+
+  ## The convertor from module options to JSON schema does not generate proper
+  ## JSON schema types, forcing us to use nullable fields for default values.
+  ## However, working with those fields in the deployment code is annoying (and
+  ## unusual for Nix programmers), so we sanitize the input here and add back
+  ## the default value by hand.
+  nonNull = x: v: if x == null then v else x;
+  panelConfig = {
+    domain = nonNull panelConfigNullable.domain "fediversity.net";
+    initialUser = nonNull panelConfigNullable.initialUser {
+      displayName = "Testy McTestface";
+      username = "test";
+      password = "testtest";
+      email = "test@test.com";
+    };
+    mastodon = nonNull panelConfigNullable.mastodon { enable = false; };
+    peertube = nonNull panelConfigNullable.peertube { enable = false; };
+    pixelfed = nonNull panelConfigNullable.pixelfed { enable = false; };
+  };
+in
+{
+  options = {
+    deployment = types.subModule {
+      module = mkOption {
+        description = ''
+          Configuration to be deployed
+        '';
+        # XXX(@fricklerhandwerk):
+        #     misusing this will produce obscure errors that will be truncated by NixOps4
+        type = lib.types.submodule ./options.nix;
+        default = panelConfig;
+      };
+      state = mkOption {
+        description = ''
+          State of the deployment
+        '';
+        # TODO: TF state
+        type = types.deferredModule;
+        default = { };
+      };
+    };
+  };
+}

deployment/flake-part.nix

@@ -2,5 +2,6 @@
   imports = [
     ./check/basic/flake-part.nix
     ./check/cli/flake-part.nix
+    ./check/panel/flake-part.nix
   ];
 }

deployment/migration.nix

@@ -0,0 +1,28 @@
+{
+  lib,
+  ...
+}:
+let
+  inherit (lib) types mkOption;
+in
+{
+  options = {
+    migration = mkOption {
+      description = "Migration of a Fediversity deployment to a Fediversity run-time environment";
+      type =
+        with types;
+        submodule {
+          runtime-environment = mkOption {
+            description = "Run-time environment to migrate the deployment to";
+            type = lib.types.submodule ./options.nix;
+            # default = { };
+          };
+          deployment = mkOption {
+            description = "Deployment to migrate";
+            type = lib.types.submodule ./deployment.nix;
+            # default = { };
+          };
+        };
+    };
+  };
+}

deployment/options.nix

@@ -8,6 +8,8 @@
   This can be fixed if we made the converter aware of [`$defs`], but that would likely amount to half a rewrite.
 
   [`$defs`]: https://json-schema.org/understanding-json-schema/structuring#defs
+
+  An example deployment configuration may be found at `configuration.sample.json`.
 */
 {
   lib,

deployment/runtime-environment.nix

@@ -0,0 +1,194 @@
+{
+  lib,
+  ...
+}:
+let
+  inherit (lib) types mkOption;
+  ssh =
+    with types;
+    (submodule {
+      host = mkOption {
+        description = "the host to access by SSH";
+        type = str;
+      };
+      username = mkOption {
+        description = "the SSH user to use";
+        type = nullOr str;
+        default = null;
+      };
+      authentication = mkOption {
+        desciption = "authentication method";
+        type = attrsOf (attrTag {
+          private-key = mkOption {
+            description = "path to the user's SSH private key";
+            type = str;
+            example = "/root/.ssh/id_ed25519";
+          };
+          password = mkOption {
+            description = "SSH password";
+            # TODO: mark as sensitive
+            type = str;
+          };
+        });
+      };
+    });
+in
+{
+  options = {
+    infrastructure = mkOption {
+      description = ''
+        Infrastructure for Fediversity applications to run on.
+
+        For adding new types, see [`nixos-generators`](https://github.com/nix-community/nixos-generators#supported-formats).
+      '';
+      type =
+        with types;
+        attrsOf (attrTag {
+          single-ssh-host = mkOption {
+            description = "A single host to deploy to by SSH.";
+            type = submodule (self: {
+              deploy = mkOption {
+                description = "deployment script";
+                type = str;
+                readOnly = true;
+                default = '''';
+              };
+              module = mkOption {
+                description = "NixOS module";
+                type = deferredModule;
+                default = {
+                  services.openssh.enable = true;
+                  # users.users.root.openssh.authorizedKeys.keys = [
+                  #   "<your SSH key here>"
+                  # ];
+                };
+                readOnly = true;
+              };
+              ssh = mkOption {
+                description = "SSH connection info";
+                type = ssh;
+              };
+            });
+          };
+          vm = mkOption {
+            description = "A VM to deploy to.";
+            type = submodule (self: {
+              deploy = mkOption {
+                description = "deployment script";
+                type = str;
+                readOnly = true;
+                default = '''';
+              };
+              module = mkOption {
+                description = "NixOS module";
+                type = deferredModule;
+                default = { };
+                readOnly = true;
+              };
+            });
+          };
+          single-nixos-machine-via-usb = mkOption {
+            description = "A machine to install the deployment to by live USB.";
+            type = submodule (self: {
+              deploy = mkOption {
+                description = "deployment script";
+                type = str;
+                readOnly = true;
+                default = '''';
+              };
+              # TODO: maybe steal some data structures from NixOS
+              module = mkOption {
+                description = "NixOS module";
+                type = deferredModule;
+                default = { };
+                readOnly = true;
+              };
+              hasNetwork = mkOption {
+                type = types.bool;
+              };
+              disks = mkOption {
+                type =
+                  with types;
+                  attrsOf (submodule {
+                    options.size = mkOption {
+                      type = types.bytes;
+                    };
+                  });
+              };
+            });
+          };
+          proxmox = mkOption {
+            description = ''
+              A ProxmoX-VE instance to deploy to.
+              See: https://registry.terraform.io/providers/bpg/proxmox/latest/docs
+            '';
+            type = submodule (self: {
+              deploy = mkOption {
+                description = "deployment script";
+                type = str;
+                readOnly = true;
+                default = '''';
+              };
+              module = mkOption {
+                description = "NixOS module";
+                type = deferredModule;
+                default = { };
+                readOnly = true;
+              };
+              endpoint = mkOption {
+                description = "API endpoint URL";
+                type = str;
+                default = "https://localhost:8006/";
+              };
+              authentication = mkOption {
+                description = ''
+                  ProxmoX authentication method.
+                  See: https://registry.terraform.io/providers/bpg/proxmox/latest/docs#authentication-methods-comparison
+                '';
+                type = attrsOf (attrTag {
+                  api-token = mkOption {
+                    description = "API token";
+                    # TODO: mark as sensitive
+                    type = str;
+                  };
+                  ticket = submodule {
+                    auth-ticket = mkOption {
+                      description = "Auth ticket";
+                      # TODO: mark as sensitive
+                      type = str;
+                    };
+                    csrf-token = mkOption {
+                      description = "CSRF prevention token";
+                      # TODO: mark as sensitive
+                      type = str;
+                    };
+                  };
+                  user = submodule {
+                    username = mkOption {
+                      description = "Username with realm";
+                      type = str;
+                      example = "root@pam";
+                    };
+                    password = mkOption {
+                      description = "User password";
+                      # TODO: mark as sensitive
+                      type = str;
+                    };
+                  };
+                });
+              };
+              insecure = mkOption {
+                description = "Skip TLS verification";
+                type = bool;
+                default = false;
+              };
+              ssh = mkOption {
+                description = "Info to access a remote ProxmoX by SSH.";
+                type = ssh;
+              };
+            });
+          };
+        });
+    };
+  };
+}

infra/common/resource.nix

@@ -1,4 +1,5 @@
 {
+  inputs,
   lib,
   config,
   ...
@@ -9,7 +10,7 @@ let
   inherit (lib.attrsets) concatMapAttrs optionalAttrs;
   inherit (lib.strings) removeSuffix;
   sources = import ../../npins;
-  inherit (sources) nixpkgs agenix disko;
+  inherit (sources) agenix disko;
 
   secretsPrefix = ../../secrets;
   secrets = import (secretsPrefix + "/secrets.nix");
@@ -26,7 +27,7 @@ in
     hostPublicKey = config.fediversityVm.hostPublicKey;
   };
 
-  inherit nixpkgs;
+  inherit (inputs) nixpkgs;
 
   ## The configuration of the machine. We strive to keep in this file only the
   ## options that really need to be injected from the resource. Everything else

infra/flake-part.nix

@@ -21,6 +21,9 @@ let
   makeResourceModule =
     { vmName, isTestVm }:
     {
+      # TODO(@fricklerhandwerk): this is terrible but IMO we should just ditch flake-parts and have our own data model for how the project is organised internally
+      _module.args = { inherit inputs; };
+
       imports =
         [
           ./common/resource.nix

npins/sources.json

@@ -25,6 +25,22 @@
       "url": null,
       "hash": "1w2gsy6qwxa5abkv8clb435237iifndcxq0s79wihqw11a5yb938"
     },
+    "disko": {
+      "type": "GitRelease",
+      "repository": {
+        "type": "GitHub",
+        "owner": "nix-community",
+        "repo": "disko"
+      },
+      "pre_releases": false,
+      "version_upper_bound": null,
+      "release_prefix": null,
+      "submodules": false,
+      "version": "v1.12.0",
+      "revision": "7121f74b976481bc36877abaf52adab2a178fcbe",
+      "url": "https://api.github.com/repos/nix-community/disko/tarball/v1.12.0",
+      "hash": "0wbx518d2x54yn4xh98cgm65wvj0gpy6nia6ra7ns4j63hx14fkq"
+    },
     "flake-inputs": {
       "type": "GitRelease",
       "repository": {
@@ -96,19 +112,6 @@
       "url": "https://api.github.com/repos/bigskysoftware/htmx/tarball/v2.0.4",
       "hash": "1c4zm3b7ym01ijydiss4amd14mv5fbgp1n71vqjk4alc35jlnqy2"
     },
-    "nix-unit": {
-      "type": "Git",
-      "repository": {
-        "type": "GitHub",
-        "owner": "nix-community",
-        "repo": "nix-unit"
-      },
-      "branch": "main",
-      "submodules": false,
-      "revision": "e9d81f6cffe67681e7c04a967d29f18c2c540af5",
-      "url": "https://github.com/nix-community/nix-unit/archive/e9d81f6cffe67681e7c04a967d29f18c2c540af5.tar.gz",
-      "hash": "1wms0wxwvxac1r1daihj5wsx1nghfk5hwdvy5cpgq481bp9x4cjn"
-    },
     "nixpkgs": {
       "type": "Git",
       "repository": {

panel/nix/configuration.nix

@@ -140,7 +140,7 @@ in
       description = ''
         A package providing NixOps4.
 
-        REVIEW: This should not be at the level of the NixOS module, but instead
+        TODO: This should not be at the level of the NixOS module, but instead
         at the level of the panel's package. Until one finds a way to grab
         NixOps4 from the package's npins-based code, we will have to do with
         this workaround.
@@ -200,7 +200,7 @@ in
     };
 
     users.users.${name} = {
-      # REVIEW[Niols]: change to system user or document why we specifically
+      # TODO[Niols]: change to system user or document why we specifically
       # need a normal user.
       isNormalUser = true;
     };

panel/src/panel/settings.py

@@ -42,6 +42,7 @@ def get_secret(name: str, encoding: str = "utf-8") -> str:
     return secret
 
 # SECURITY WARNING: keep the secret key used in production secret!
+# This is used nowhere but is required by Django.
 SECRET_KEY = get_secret("SECRET_KEY")
 
 # SECURITY WARNING: don't run with debug turned on in production!

services/default.nix

@@ -6,8 +6,8 @@
 }:
 {
   tests = {
-    mastodon = import ./tests/mastodon.nix { inherit pkgs; };
-    pixelfed-garage = import ./tests/pixelfed-garage.nix { inherit pkgs; };
-    peertube = import ./tests/peertube.nix { inherit pkgs; };
+    mastodon = pkgs.nixosTest ./tests/mastodon.nix;
+    pixelfed-garage = pkgs.nixosTest ./tests/pixelfed-garage.nix;
+    peertube = pkgs.nixosTest ./tests/peertube.nix;
   };
 }

services/tests/mastodon.nix

@@ -42,7 +42,7 @@ let
       '';
 in
 
-pkgs.nixosTest {
+{
   name = "mastodon";
 
   nodes = {

services/tests/peertube.nix

@@ -161,7 +161,7 @@ let
   '';
 in
 
-pkgs.nixosTest {
+{
   name = "peertube";
 
   nodes = {

services/tests/pixelfed-garage.nix

@@ -114,7 +114,7 @@ let
         ${seleniumQuit}'';
 
 in
-pkgs.nixosTest {
+{
   name = "test-pixelfed-garage";
 
   nodes = {

test.nix

@@ -0,0 +1,45 @@
+let
+  inherit (import ./default.nix { }) pkgs;
+  inherit (pkgs) lib;
+  eval =
+    module:
+    (lib.evalModules {
+      modules = [
+        module
+        ./deployment/application.nix
+      ];
+    }).config;
+in
+{
+  test-foo = {
+    expr =
+      let
+        example = eval {
+          runtime-environments.bar.nixos = {
+            module =
+              { ... }:
+              {
+                system.stateVersion = "25.05";
+              };
+          };
+          applications.foo = {
+            module =
+              { pkgs, ... }:
+              {
+                environment.systemPackages = [
+                  pkgs.hello
+                ];
+              };
+          };
+        };
+      in
+      {
+        has-runtime = example.runtime-environments.bar.nixos ? module;
+        has-application = example.applications.foo ? module;
+      };
+    expected = {
+      has-runtime = true;
+      has-application = true;
+    };
+  };
+}