doc, vm, template

.gitignore

@@ -6,3 +6,4 @@
 /docs/reference/module-options
 /.nixos-test-history
 /result*
+/*.qcow2

README.md

@@ -15,26 +15,13 @@ Collection of Cardano related Nix packages and NixOS modules, with a special foc
 }
 ```
 
-This will configure `cardano-node` and `ogmios` on the `preview` network.
+This example NixOS configuration will run `cardano-node` and related services on the `preview` network.
 
 ### Read the [Documentation](https://mlabs-haskell.github.io/cardano.nix/)
 
-## Setup
+### Development
 
-Install nix and enable flakes, eg. with [Determinate nix installer](https://github.com/DeterminateSystems/nix-installer).
-
-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.
+Development is supported on linux systems. Virtual machines are run with `qemu` so `kvm` is recommended. Follow the [installation guide](https://mlabs-haskell.github.io/cardano.nix/getting-started/installation/) to set up nix.
 
 `cardano.nix` provides a devshell that includes various tools to build, test, run and update the project:
 
@@ -64,7 +51,7 @@ Development is supported on linux systems. Virtual machines are run with `qemu`
   update-pre-commit-hooks - update git pre-commit hooks
 ```
 
-A `.envrc` is also provided, using [direnv]() and [nix-direnv](https://github.com/nix-community/nix-direnv) is suggested.
+A `.envrc` file is also provided, using [direnv](https://direnv.net/) and [nix-direnv](https://github.com/nix-community/nix-direnv) is suggested.
 
 ### Running Integration Tests
 

configurations/default.nix

@@ -0,0 +1,32 @@
+{
+  self,
+  inputs,
+  ...
+}: {
+  flake.nixosConfigurations = {
+    vm-preview = inputs.nixpkgs.lib.nixosSystem {
+      modules = [
+        self.nixosModules.default
+        ./preview.nix
+        ./vm.nix
+        {nixpkgs.hostPlatform = "x86_64-linux";}
+      ];
+    };
+  };
+  perSystem = _: {
+    apps = {
+      vm-preview = {
+        type = "app";
+        program = "${self.nixosConfigurations.vm-preview.config.system.build.vm}/bin/run-nixos-vm";
+      };
+    };
+    devshells.default.commands = [
+      {
+        name = "vm-preview";
+        category = "examples";
+        command = "${self.nixosConfigurations.vm-preview.config.system.build.vm}/bin/run-nixos-vm";
+        help = "Start vm with cardano services on the preview network and ports forwarded to host";
+      }
+    ];
+  };
+}

configurations/preview.nix

@@ -0,0 +1,6 @@
+{
+  cardano = {
+    enable = true;
+    network = "preview";
+  };
+}

configurations/vm.nix

@@ -0,0 +1,31 @@
+{modulesPath, ...}: {
+  imports = [
+    (modulesPath + "/virtualisation/qemu-vm.nix")
+    (modulesPath + "/profiles/qemu-guest.nix")
+  ];
+
+  # WARNING: don't use this in production
+  # Allow root login without password, auto login
+  users.users.root.password = "";
+  services.getty.autologinUser = "root";
+
+  virtualisation = {
+    cores = 2;
+    memorySize = 2048;
+    diskSize = 100 * 1024;
+    forwardPorts = [
+      {
+        # cardano-node
+        from = "host";
+        host.port = 3001;
+        guest.port = 3001;
+      }
+      {
+        # ogmios
+        from = "host";
+        host.port = 1337;
+        guest.port = 1337;
+      }
+    ];
+  };
+}

docs/default.nix

@@ -109,25 +109,29 @@ in {
         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";
+    packages = {
+      docs = stdenv.mkDerivation {
+        src = ../.; # FIXME: use config.flake-root.package here
+        name = "cardano-nix-docs";
 
-      nativeBuildInputs = [my-mkdocs];
+        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
-      '';
+        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
-      '';
+        installPhase = ''
+          mv site $out
+          rm $out/default.nix  # Clean nwanted side-effect of mkdocs
+        '';
+
+        passthru.serve = config.packages.docs-serve;
+      };
 
-      passthru.serve = pkgs.writeShellScriptBin "serve" ''
+      docs-serve = pkgs.writeShellScriptBin "docs-serve" ''
         set -euo pipefail
 
         # link in options reference
@@ -155,7 +159,7 @@ in {
           inherit category;
           name = "docs-serve";
           help = "serve documentation web page";
-          command = "nix run .#docs.serve";
+          command = "nix run .#docs-serve";
         }
         {
           inherit category;

docs/development/contributing.md

@@ -1 +1,22 @@
-FIXME
+There are several ways you can contribute.
+
+## Reporting issues
+
+- Search the issue tracker before creating a new issue
+- Provide detailed steps to reproduce the issue
+- Include as much information as possible
+
+## Proposing features
+
+- Use the issue tracker to propose new features
+- Feel free to also propose a PR implementing it
+
+## Code style guidelines
+
+- Format everything with `nix fmt .`
+
+## Checks
+
+- You can verify that all checks pass with `nix flake check`
+
+Thank you for contributing to `cardano.nix`! Your help is greatly appreciated 😊

docs/getting-started/deploy.md

@@ -0,0 +1,34 @@
+In order to access all the options available in `cardano.nix`, the [NixOS module](https://zero-to-nix.com/concepts/nixos#modules) provided by this project has to be included in a [NixOS configuration](https://zero-to-nix.com/concepts/nixos#configuration) and deployed to a (local or remote or virtual) machine.
+
+### Start new project with flake template
+
+An easy way to get started is to use the [flake template](https://zero-to-nix.com/concepts/flakes#templates) provided by this project. Here's how to start a new project using the template:
+
+```
+mkdir myproject
+cd myproject
+nix flake init --template github:mlabs-haskell/cardano.nix
+git init
+git add .
+```
+
+### Run a virtual machine
+
+The default template provides a virtual machine configuration starting all the services in the preview testnet. Here's how to run it:
+
+`nix run .#vm`
+
+This machine is set up just like the one in [Run a VM](../vm), but can be customized.
+
+### Look around
+
+The file named `flake.nix` includes:
+
+- a [https://zero-to-nix.com/concepts/nixos#configuration](NixOS configuration) to run cardano services, under `nixosConfigurations.server`
+- an app to run the virtual machine as above, under `apps.x86_64-linux.vm`
+
+The file `configuration.nix` is the configuration for the machine.
+
+### 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 `configuration.nix` to configure the system.

docs/getting-started/installation.md

@@ -1 +1,28 @@
-FIXME
+### Requirements
+
+- linux
+- nix
+- kvm (optional, for running virtual machine tests)
+
+## Setup
+
+Follow [this guide](https://zero-to-nix.com/start/install) to Install nix with [flakes](https://nix.dev/concepts/flakes.html) enabled.
+
+### Binary cache
+
+You can optionally use this project's binary cache to skip building software and download it instead. 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).
+
+### Check that it works
+
+`nix --version`
+
+### Learn more
+
+For an introduction to the Nix ecosystem, check out [Zero to Nix](https://zero-to-nix.com/). Learn more about [Nix flakes](https://zero-to-nix.com/concepts/flakes) and [NixOS](https://zero-to-nix.com/concepts/nixos).

docs/getting-started/vm.md

@@ -0,0 +1,14 @@
+This project provides a virtual machine configuration with all cardano services.
+
+`nix run github:mlabs-haskell/cardano.nix#vm-preview`
+
+Log in with user `root`. The password is empty.
+
+The following services will be started and ports forwarded to the host:
+
+|cardano-node|3001|
+|ogmios|1337|
+
+In the virtual machine, `cardano-cli` is available to query the node.
+
+`cardano-cli query tip --testnet-magic 2`

docs/index.md

@@ -1,4 +1,41 @@
 # About the Project
 
-`cardano.nix` is a collection of [Nix](https://nixos.org) packages and [NixOS](https://nixos.wiki/wiki/NixOS_modules) modules
-designed to make it easier to operate [Cardano](https://cardano.org) related services and infrastructure.
+`cardano.nix` is a collection of [Nix](https://nixos.org) packages and [NixOS modules](https://zero-to-nix.com/concepts/nixos#modules) designed to make it easy to operate [Cardano](https://cardano.org) related services and infrastructure.
+
+### Why?
+
+[Nix](https://zero-to-nix.com/concepts/nix) is a declarative package manager ensuring hash-based reproducible build and dependency management. [NixOS](https://zero-to-nix.com/concepts/nixos) is a Linux distribution with a declarative configuration system. With NixOS, entire system configurations are reproducible and work the same regardless of the current state of the system. Updates (and rollbacks) are atomic: they either work or nothing happens, so they can't get stuck halfway through. These features are responsible for the increased reliability of a NixOS system, making it an attractive DevOps tool for deploying services.
+
+### What?
+
+The `cardano.nix` project aims to provide [NixOS modules](https://zero-to-nix.com/concepts/nixos#modules) for Cardano services such as `cardano-node`, `ogmios`, `kupo`, `cardano-db-sync`, as well as auxiliary modules such as firewall and HTTP(S), making it easy to deploy these services in production. Very little configuration is needed to run the services with sane defaults that are easy to customize. The services can be run on the same host or in a distributed cluster, and a HTTPS proxy module is also provided.
+
+### How?
+
+Here are some motivating examples.
+
+This NixOS configuration will start `cardano-node` and related services on the `preview` testnet.
+
+```nix
+{
+  cardano = {
+    enable = true;
+    network = preview;
+  };
+}
+```
+
+This snippet will configure a HTTPS reverse proxy and load balancer with ACME certificates from Let's Encrypt. DNS records need to be set up and the backend servers (configured as above) need to be reachable.
+
+```nix
+{
+  cardano.http.enable = true;
+  services.http-proxy = {
+    domainName = "preview.example.com";
+    https.enable = true;
+    servers = ["server1" "server2"];
+  };
+};
+```
+
+Configurations including the above can be deployed to a laptop, a virtual machine, a cloud instance, a container, or any other system running NixOS. Example configurations and shortcuts to run virtual machines are provided as part of the project.