add further comments

launch/README.md

@@ -1,7 +1,15 @@
 # service deployment
 
+deploys [NixOS](https://nixos.org/) templates using [OpenTofu](https://opentofu.org/).
+
+## requirements
+
+- [nix](https://nix.dev/)
+
 ## usage
 
+### development
+
 before using other commands, if not using direnv:
 
 ```sh
@@ -13,3 +21,8 @@ then to initialize, or after updating pins or TF providers:
 ```sh
 setup
 ```
+
+## implementing
+
+proper documentation TODO.
+until then, a reference implementation may be found in [`panel/`](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/panel).

launch/main.tf

@@ -91,8 +91,11 @@ resource "terraform_data" "nixos" {
             configuration = {
               # note interpolations here TF ones
               imports = [
-                ${path.root}/options.nix
+                # shared NixOS config
                 ${path.root}/shared.nix
+                # FIXME: separate template options by service
+                ${path.root}/options.nix
+                # for service `mastodon` import `mastodon.nix`
                 ${path.root}/${each.key}.nix
                 # FIXME: get VM details from TF
                 ${path.root}/../infra/test-machines/${each.value.hostname}
@@ -100,7 +103,7 @@ resource "terraform_data" "nixos" {
               # nix path for debugging
               nix.nixPath = [ "${local.nix_path}" ];
             } //
-            # info passed in thru json from TF
+            # template parameters passed in from TF thru json
             builtins.fromJSON "${replace(jsonencode({
               terraform = {
                 domain = var.domain

launch/options.nix

@@ -1,4 +1,4 @@
-# TODO: could (part of) this be generated somehow?
+# TODO: could (part of) this be generated somehow? c.f #275
 {
   lib,
   ...

launch/variables.tf

@@ -1,4 +1,4 @@
-# TODO: generate (part of) the variables?
+# TODO: (partially) generate, say from nix modules, c.f. #275
 
 variable "domain" {
   type = string

panel/nix/python-packages/django-pydantic-field/default.nix

@@ -1,3 +1,4 @@
+# TODO upstream, see #248
 {
   lib,
   buildPythonPackage,