mlabs-haskell · brainrake · May 17, 2024 · May 3, 2024 · May 3, 2024 · May 9, 2024
diff --git a/README.md b/README.md
@@ -15,22 +15,56 @@ Collection of Cardano related Nix packages and NixOS modules, with a special foc
 }
 ```
 
-This example NixOS configuration will run `cardano-node` and related services on the `preview` network.
+This will configure `cardano-node` and `ogmios` on the `preview` network.
 
-#### Read the [Documentation](https://mlabs-haskell.github.io/cardano.nix/)
+### Read the [Documentation](https://mlabs-haskell.github.io/cardano.nix/)
 
-### Development
+## Setup
 
-To get started, [install nix with flakes enabled](https://zero-to-nix.com/start/install). Enter the development shell and a list of useful tools will be displayed
+Install nix and enable flakes, eg. with [Determinate nix installer](https://github.com/DeterminateSystems/nix-installer).
 
-```bash
-$ nix develop
+Use the project's binary cache to skip builds. Edit `/etc/nix/nix.conf` (or related settings in NixOS config) and merge the new values separated by spaces into the options:
+
+```
+substituters = ... https://cache.staging.mlabs.city/cardano-nix
+trusted-public-keys = ... cardano-nix:BQ7QKgoQQAuL3Kh6pfIJ8oxrihUbUSxf6tN9SxyW608=
+```
+
+Don't edit `~/.config/nix/nix.conf` in your home directory. Don't add users to `trusted-users` because it is [insecure](https://nixos.org/manual/nix/stable/command-ref/conf-file.html?highlight=trusted-user#conf-trusted-users).
+
+### Development Shell
+
+Development is supported on linux systems. Virtual machines are run with `qemu` so `kvm` is recommended.
+
+`cardano.nix` provides a devshell that includes various tools to build, test, run and update the project:
+
+```
+❯ nix develop
 ...
 ❄️ Welcome to the cardano.nix devshell ❄️
-...
+
+[documentation]
+
+  docs-build              - build documentation
+  docs-serve              - serve documentation web page
+
+[general commands]
+
+  menu                    - prints this menu
+
+[tests]
+
+  build-all               - build all packages and checks with `devour-flake`
+  check                   - run `nix flake check`
+  run-vm-test             - list and run virtual machine integration tests
+
+[tools]
+
+  fmt                     - format the source tree
+  update-pre-commit-hooks - update git pre-commit hooks
 ```
 
-See the [Development Documentation](https://mlabs-haskell.github.io/cardano.nix/development/develop/) for more information.
+A `.envrc` is also provided, using [direnv]() and [nix-direnv](https://github.com/nix-community/nix-direnv) is suggested.
 
 ### Running Integration Tests
 

diff --git a/docs/default.nix b/docs/default.nix
@@ -6,173 +6,85 @@
 }: let
   rootConfig = config;
 in {
-  perSystem = {
-    config,
-    lib,
-    pkgs,
-    ...
-  }: let
-    inherit (pkgs) stdenv python311Packages;
+  imports = [
+    ./render.nix
+  ];
 
-    my-mkdocs = let
-      inherit (python311Packages) mkdocs;
-    in
-      pkgs.runCommand "my-mkdocs"
+  renderDocs = {
+    enable = true;
+    sidebarOptions = [
       {
-        buildInputs = [
-          mkdocs
-          python311Packages.mkdocs-material
-        ];
-      } ''
-        mkdir -p $out/bin
-
-        cat <<MKDOCS > $out/bin/mkdocs
-        #!${pkgs.bash}/bin/bash
-        set -euo pipefail
-        export PYTHONPATH=$PYTHONPATH
-        exec ${mkdocs}/bin/mkdocs "\$@"
-        MKDOCS
-
-        chmod +x $out/bin/mkdocs
-      '';
-
-    eachOptions = removeAttrs rootConfig.flake.nixosModules ["default"];
-
-    eachOptionsDoc =
-      lib.mapAttrs' (
-        name: value:
-          lib.nameValuePair
-          # take foo.options and turn it into just foo
-          (builtins.head (lib.splitString "." name))
-          (pkgs.nixosOptionsDoc {
-            # By default `nixosOptionsDoc` will ignore internal options but we want to show them
-            # This hack will make all the options not internal and visible and optionally append to the
-            # description a new field which is then corrected rendered as it was a native field
-            transformOptions = opt:
-              opt
-              // {
-                internal = false;
-                visible = true;
-                description = ''
-                  ${opt.description}
-                  ${lib.optionalString opt.internal "*Internal:* true"}
-                '';
-              };
-            options =
-              (lib.evalModules {
-                modules = (import "${inputs.nixpkgs}/nixos/modules/module-list.nix") ++ [value];
-                specialArgs = {inherit pkgs;};
-              })
-              .options
-              .cardano;
-          })
-      )
-      eachOptions;
-
-    statements =
-      lib.concatStringsSep "\n"
-      (lib.mapAttrsToList (n: v: ''
-          path=$out/${n}.md
-          cat ${v.optionsCommonMark} >> $path
-        '')
-        eachOptionsDoc);
-
-    githubUrl = "https://github.com/mlabs-haskell/cardano.nix/tree/main";
-
-    options-doc = pkgs.runCommand "nixos-options" {} ''
-      mkdir $out
-      ${statements}
-      # Fixing links to storage to files in github
-      find $out -type f | xargs -n1 sed -i -e "s,${self.outPath},${githubUrl},g" -e "s,file://https://,https://,g"
-    '';
-
-    docsPath = "./docs/reference/module-options";
-
-    index = {
-      nav = [
-        {
-          "Reference" = [{"NixOS Module Options" = lib.mapAttrsToList (n: _: "reference/module-options/${n}.md") eachOptionsDoc;}];
-        }
-      ];
-    };
-
-    indexYAML =
-      pkgs.runCommand "index.yaml" {
-        nativeBuildInputs = [pkgs.yq-go];
-        index = builtins.toFile "index.json" (builtins.unsafeDiscardStringContext (builtins.toJSON index));
-      } ''
-        yq -o yaml $index >$out
-      '';
-
-    mergedMkdocsYaml =
-      pkgs.runCommand "mkdocs.yaml" {
-        nativeBuildInputs = [pkgs.yq-go];
-      } ''
-        yq '. *+ load("${indexYAML}")' ${./mkdocs.yml} -o yaml >$out
-      '';
-  in {
-    packages = {
-      docs = stdenv.mkDerivation {
-        src = ../.; # FIXME: use config.flake-root.package here
-        name = "cardano-nix-docs";
-
-        nativeBuildInputs = [my-mkdocs];
-
-        buildPhase = ''
-          ln -s ${options-doc} ${docsPath}
-          # mkdocs expect mkdocs one level upper than `docs/`, but we want to keep it in `docs/`
-          cp ${mergedMkdocsYaml} mkdocs.yml
-          mkdocs build -f mkdocs.yml -d site
-        '';
-
-        installPhase = ''
-          mv site $out
-          rm $out/default.nix  # Clean nwanted side-effect of mkdocs
-        '';
-
-        passthru.serve = config.packages.docs-serve;
-      };
-
-      docs-serve = pkgs.writeShellScriptBin "docs-serve" ''
-        set -euo pipefail
-
-        # link in options reference
-        rm -f ${docsPath}
-        ln -s ${options-doc} ${docsPath}
-        rm -f mkdocs.yml
-        ln -s ${mergedMkdocsYaml} mkdocs.yml
-
-        BASEDIR="$(${lib.getExe config.flake-root.package})"
-        cd $BASEDIR
-
-        cat <<EOF
-        NOTE: Documentation/index autogenerated from NixOS options doesn't reload automatically
-        NOTE: Please restart 'docs-serve' for it
-        EOF
-        ${my-mkdocs}/bin/mkdocs serve
-      '';
-    };
-
-    devshells.default = {
-      commands = let
-        category = "documentation";
-      in [
-        {
-          inherit category;
-          name = "docs-serve";
-          help = "serve documentation web page";
-          command = "nix run .#docs-serve";
-        }
-        {
-          inherit category;
-          name = "docs-build";
-          help = "build documentation";
-          command = "nix build .#docs";
-        }
-      ];
-      packages = [
-        my-mkdocs
-      ];
-    };
+        anchor = "cardano";
+        modules = [rootConfig.flake.nixosModules.cardano];
+        namespaces = ["cardano"];
+      }
+      {
+        anchor = "cardano.cli";
+        modules = [rootConfig.flake.nixosModules.cli];
+        namespaces = ["cardano.cli"];
+      }
+      {
+        anchor = "cardano.node";
+        modules = [rootConfig.flake.nixosModules.node];
+        namespaces = ["cardano.node"];
+      }
+      {
+        anchor = "services.cardano-node";
+        modules = [rootConfig.flake.nixosModules.node];
+        namespaces = ["services.cardano-node"];
+      }
+      {
+        anchor = "cardano.ogmios";
+        modules = [rootConfig.flake.nixosModules.ogmios];
+        namespaces = ["cardano.ogmios"];
+      }
+      {
+        anchor = "services.ogmios";
+        modules = [rootConfig.flake.nixosModules.ogmios];
+        namespaces = ["services.ogmios"];
+      }
+      {
+        anchor = "cardano.kupo";
+        modules = [rootConfig.flake.nixosModules.kupo];
+        namespaces = ["cardano.kupo"];
+      }
+      {
+        anchor = "services.kupo";
+        modules = [rootConfig.flake.nixosModules.kupo];
+        namespaces = ["services.kupo"];
+      }
+      {
+        anchor = "cardano.db-sync";
+        modules = [rootConfig.flake.nixosModules.db-sync];
+        namespaces = ["cardano.db-sync"];
+      }
+      {
+        anchor = "services.cardano-db-sync";
+        modules = [(rootConfig.flake.nixosModules.db-sync // {config.services.cardano-db-sync.cluster = "mainnet";})];
+        namespaces = ["services.cardano-db-sync"];
+      }
+      {
+        anchor = "cardano.http";
+        modules = [rootConfig.flake.nixosModules.http];
+        namespaces = ["cardano.http"];
+      }
+      {
+        anchor = "services.http-proxy";
+        modules = [rootConfig.flake.nixosModules.http];
+        namespaces = ["services.http-proxy"];
+      }
+    ];
+
+    # Replace `/nix/store` related paths with public urls
+    fixups = [
+      {
+        storePath = self.outPath;
+        githubUrl = "https://github.com/mlabs-haskell/cardano.nix/tree/main";
+      }
+      {
+        storePath = inputs.cardano-node.outPath;
+        githubUrl = "https://github.com/IntersectMBO/cardano-node/tree/master";
+      }
+    ];
   };
 }
diff --git a/docs/getting-started/deploy.md b/docs/getting-started/deploy.md
@@ -18,7 +18,7 @@ The default template provides a virtual machine configuration starting all the s
 
 `nix run .#vm`
 
-This machine is set up just like the one in [Run a VM](../vm), but can be customized.
+This machine is set up just like the one in [Run a VM](vm.md), but can be customized.
 
 ### Look around
 
@@ -39,7 +39,7 @@ This NixOS configuration sets virtual machine options such as cores, memory and
 
 ### Customize
 
-To learn more, browse available [NixOS options in nixpkgs](https://search.nixos.org/options) and [NixOS options provided by cardano.nix](../../reference/module-options/cardano/) (see other modules in the menu on the left). You can ad these options to `preview.nix` to configure the system.
+To learn more, browse available [NixOS options in nixpkgs](https://search.nixos.org/options) and [NixOS options provided by cardano.nix](../reference/module-options/cardano.md) (see other modules in the menu on the left). You can ad these options to `preview.nix` to configure the system.
 
 ### Deployment options
 
@@ -52,7 +52,7 @@ The configuration can be deployed to any target running NixOS, such as:
 There are a variety of resources to help install NixOS:
 
 - the [official documentation installation guide](https://nixos.org/manual/nixos/stable/#ch-installation)
-- [https://nix-community.github.io/nixos-anywhere/quickstart.html](nixos-anyware) to deploy on existing hosts running other distrbutions
+- [nixos-anywhere](https://nix-community.github.io/nixos-anywhere/quickstart.html) to deploy on existing hosts running other distrbutions
 - various web resources for specific cloud providers or other circumstances
 
 With a running NixOS installation and a NixOS configuration `server` in a nix flake, this command will deploy the server:

diff --git a/docs/index.md b/docs/index.md
@@ -4,7 +4,7 @@
 
 ### Why?
 
-[Nix](https://zero-to-nix.com/concepts/nix) is a [declarative](https://zero-to-nix.com/concepts/declarative) package manager ensuring hash-based [dependency pinning](https://zero-to-nix.com/concepts/pinning) and [reproducible](<[reproducible](https://zero-to-nix.com/concepts/reproducibility)>) builds. [NixOS](https://zero-to-nix.com/concepts/nixos) is a Linux distribution with a [declarative configuration](https://zero-to-nix.com/concepts/nixos#configuration) system providing [atomic](https://zero-to-nix.com/concepts/nixos#atomicity) updates and [rollbacks](https://zero-to-nix.com/concepts/nixos#rollbacks). These features are responsible for the increased reliability of a NixOS system, making it an attractive DevOps toolset for deploying Cardano services.
+[Nix](https://zero-to-nix.com/concepts/nix) is a [declarative](https://zero-to-nix.com/concepts/declarative) package manager ensuring hash-based [dependency pinning](https://zero-to-nix.com/concepts/pinning) and [reproducible](https://zero-to-nix.com/concepts/reproducibility) builds. [NixOS](https://zero-to-nix.com/concepts/nixos) is a Linux distribution with a [declarative configuration](https://zero-to-nix.com/concepts/nixos#configuration) system providing [atomic](https://zero-to-nix.com/concepts/nixos#atomicity) updates and [rollbacks](https://zero-to-nix.com/concepts/nixos#rollbacks). These features are responsible for the increased reliability of a NixOS system, making it an attractive DevOps toolset for deploying Cardano services.
 
 ### What?