From 21fd8e6dfeb5fd5f8d37424f07a5b77c3af20637 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rton=20Boros?= Date: Mon, 29 Apr 2024 09:17:20 +0000 Subject: [PATCH 01/11] doc, vm, template --- .gitignore | 1 + README.md | 21 +++----------- configurations/default.nix | 24 ++++++++++++++++ configurations/preview.nix | 6 ++++ configurations/vm.nix | 21 ++++++++++++++ docs/getting-started/deploy.md | 40 +++++++++++++++++++++++++++ docs/getting-started/installation.md | 29 +++++++++++++++++++- docs/getting-started/vm.md | 16 +++++++++++ docs/index.md | 41 ++++++++++++++++++++++++++-- docs/mkdocs.yml | 8 ++++-- flake.nix | 5 ++++ template/configuration.nix | 6 ++++ template/flake.nix | 25 +++++++++++++++++ template/vm.nix | 21 ++++++++++++++ 14 files changed, 241 insertions(+), 23 deletions(-) create mode 100644 configurations/default.nix create mode 100644 configurations/preview.nix create mode 100644 configurations/vm.nix create mode 100644 docs/getting-started/deploy.md create mode 100644 docs/getting-started/vm.md create mode 100644 template/configuration.nix create mode 100644 template/flake.nix create mode 100644 template/vm.nix diff --git a/.gitignore b/.gitignore index 5d15a67..c72a107 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ /docs/reference/module-options /.nixos-test-history /result* +/*.qcow2 diff --git a/README.md b/README.md index ee492c5..2a81be7 100644 --- a/README.md +++ b/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]() and [nix-direnv](https://github.com/nix-community/nix-direnv) is suggested. ### Running Integration Tests diff --git a/configurations/default.nix b/configurations/default.nix new file mode 100644 index 0000000..0be236a --- /dev/null +++ b/configurations/default.nix @@ -0,0 +1,24 @@ +{ + 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"; + }; + }; + }; +} diff --git a/configurations/preview.nix b/configurations/preview.nix new file mode 100644 index 0000000..27ced7a --- /dev/null +++ b/configurations/preview.nix @@ -0,0 +1,6 @@ +{ + cardano = { + enable = true; + network = "preview"; + }; +} diff --git a/configurations/vm.nix b/configurations/vm.nix new file mode 100644 index 0000000..c2935c1 --- /dev/null +++ b/configurations/vm.nix @@ -0,0 +1,21 @@ +{ + modulesPath, + lib, + pkgs, + ... +}: { + imports = [ + (modulesPath + "/virtualisation/qemu-vm.nix") + (modulesPath + "/profiles/qemu-guest.nix") + ]; + + # WARNING: don't use this in production + # Allow root login without password + users.users.root.hashedPasswordFile = lib.mkOverride 150 "${pkgs.writeText "hashed-password.root" ""}"; + + virtualisation = { + cores = 2; + memorySize = 2048; + diskSize = 100 * 1024; + }; +} diff --git a/docs/getting-started/deploy.md b/docs/getting-started/deploy.md new file mode 100644 index 0000000..ea6b57f --- /dev/null +++ b/docs/getting-started/deploy.md @@ -0,0 +1,40 @@ +## Deploy Cardano services + +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 [https://zero-to-nix.com/concepts/nixos#configuration](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 [Running 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](https://mlabs-haskell.github.io/cardano.nix/reference/module-options/cardano/) (see other modules in the menu on the left). + +Add these options to `configuration.nix` to + +### diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 9d6cf4b..d2a58ad 100644 --- a/docs/getting-started/installation.md +++ b/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) diff --git a/docs/getting-started/vm.md b/docs/getting-started/vm.md new file mode 100644 index 0000000..efe1262 --- /dev/null +++ b/docs/getting-started/vm.md @@ -0,0 +1,16 @@ +## Run Cardano services in a Virtual Machine + +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` diff --git a/docs/index.md b/docs/index.md index 24dba34..9bd7711 100644 --- a/docs/index.md +++ b/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. + +``` +{ + 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. + +``` +{ + 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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 481405f..df0b24d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,11 +59,13 @@ markdown_extensions: nav: - index.md - - license.md + - Getting Started: + - Installation: getting-started/installation.md + - Run a VM: getting-started/vm.md + - Deploy: getting-started/deploy.md - Development: - development/contributing.md - - Getting Started: - - getting-started/installation.md + - license.md ## Section commented out below, would be autogenerated during docs rendering # - Reference: # - NixOS Module Options: diff --git a/flake.nix b/flake.nix index 1cdbda5..c4637e3 100644 --- a/flake.nix +++ b/flake.nix @@ -56,6 +56,7 @@ imports = [ ./checks ./ci + ./configurations ./docs ./formatter ./modules @@ -63,6 +64,10 @@ ./tests ./packages ]; + flake.templates.default = { + path = ./template; + description = "Example flake using cardano.nix"; + }; systems = [ "x86_64-linux" "aarch64-linux" diff --git a/template/configuration.nix b/template/configuration.nix new file mode 100644 index 0000000..27ced7a --- /dev/null +++ b/template/configuration.nix @@ -0,0 +1,6 @@ +{ + cardano = { + enable = true; + network = "preview"; + }; +} diff --git a/template/flake.nix b/template/flake.nix new file mode 100644 index 0000000..6cc598d --- /dev/null +++ b/template/flake.nix @@ -0,0 +1,25 @@ +{ + description = "Example flake using cardano.nix"; + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + cardano-nix.url = "github:mlabs-haskell/cardano.nix/main"; + }; + outputs = inputs @ {self, ...}: { + nixosConfigurations = { + server-vm = inputs.nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ + inputs.cardano-nix.nixosModules.default + ./configuration.nix + ./vm.nix + ]; + }; + }; + apps.x86_64-linux = { + server-vm = { + type = "app"; + program = "${self.nixosConfigurations.server-vm.config.system.build.vm}/bin/run-nixos-vm"; + }; + }; + }; +} diff --git a/template/vm.nix b/template/vm.nix new file mode 100644 index 0000000..c2935c1 --- /dev/null +++ b/template/vm.nix @@ -0,0 +1,21 @@ +{ + modulesPath, + lib, + pkgs, + ... +}: { + imports = [ + (modulesPath + "/virtualisation/qemu-vm.nix") + (modulesPath + "/profiles/qemu-guest.nix") + ]; + + # WARNING: don't use this in production + # Allow root login without password + users.users.root.hashedPasswordFile = lib.mkOverride 150 "${pkgs.writeText "hashed-password.root" ""}"; + + virtualisation = { + cores = 2; + memorySize = 2048; + diskSize = 100 * 1024; + }; +} From 425838afac372dc715222529bfc3ff1619ce8eff Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 11:46:10 +0200 Subject: [PATCH 02/11] Specify language for synyax highligthing --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9bd7711..c14af6b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ Here are some motivating examples. This NixOS configuration will start `cardano-node` and related services on the `preview` testnet. -``` +```nix { cardano = { enable = true; @@ -27,7 +27,7 @@ This NixOS configuration will start `cardano-node` and related services on the ` 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 = { From f5101d4a2d1812c5018e143ef593f69d56f75df4 Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 11:55:59 +0200 Subject: [PATCH 03/11] Expose `docs-serve` (also) directly as flake package --- docs/default.nix | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/default.nix b/docs/default.nix index 5dec7af..bcdbb9f 100644 --- a/docs/default.nix +++ b/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; From ead3499f6a66f91266303225a6797183f0cca68c Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 11:56:58 +0200 Subject: [PATCH 04/11] Add missing direnv.net link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2a81be7..c088d6d 100644 --- a/README.md +++ b/README.md @@ -51,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` file 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 From 2fb9789f7d01c042c0cf3077a1b556ed3d9c5efc Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 12:00:24 +0200 Subject: [PATCH 05/11] Typo --- docs/getting-started/deploy.md | 2 +- docs/getting-started/installation.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/deploy.md b/docs/getting-started/deploy.md index ea6b57f..5704976 100644 --- a/docs/getting-started/deploy.md +++ b/docs/getting-started/deploy.md @@ -1,6 +1,6 @@ ## Deploy Cardano services -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 [https://zero-to-nix.com/concepts/nixos#configuration](NixOS configuration) and deployed to a (local or remote or virtual) machine. +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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index d2a58ad..00b0510 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -25,4 +25,4 @@ Don't edit `~/.config/nix/nix.conf` in your home directory. Don't add users to ` ### 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) +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). From e5106dea6bd526bbbd1b10d457a65c4ce0842feb Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 12:04:31 +0200 Subject: [PATCH 06/11] Fix dead link --- docs/getting-started/deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/deploy.md b/docs/getting-started/deploy.md index 5704976..1eba190 100644 --- a/docs/getting-started/deploy.md +++ b/docs/getting-started/deploy.md @@ -20,7 +20,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 [Running a VM](vm), but can be customized. +This machine is set up just like the one in [Run a VM](../vm), but can be customized. ### Look around From d0db92ec67ca39bfa36e4352fd8b609b3ee36ed8 Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 12:07:11 +0200 Subject: [PATCH 07/11] Relativize link --- docs/getting-started/deploy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/deploy.md b/docs/getting-started/deploy.md index 1eba190..b83e7d7 100644 --- a/docs/getting-started/deploy.md +++ b/docs/getting-started/deploy.md @@ -33,7 +33,7 @@ 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](https://mlabs-haskell.github.io/cardano.nix/reference/module-options/cardano/) (see other modules in the menu on the left). +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). Add these options to `configuration.nix` to From eed08f78e9b798d92ee79ed7ac2bb0cfc637cdf7 Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 12:10:39 +0200 Subject: [PATCH 08/11] Not treat as a markdown list --- docs/license.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/license.md b/docs/license.md index f336e5c..9e02e09 100644 --- a/docs/license.md +++ b/docs/license.md @@ -4,7 +4,7 @@ http://www.apache.org/licenses/ # TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION -1. Definitions. +1- Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. @@ -26,31 +26,31 @@ http://www.apache.org/licenses/ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. -2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. +2- Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. -3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. +3- Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. -4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: +4- Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: - (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and +(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and - (b) You must cause any modified files to carry prominent notices stating that You changed the files; and +(b) You must cause any modified files to carry prominent notices stating that You changed the files; and - (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and +(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and - (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. +(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. - You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. +You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. -5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. +5- Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. -6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. +6- Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. -7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. +7- Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. -8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. +8- Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. -9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. +9- Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS From 51476b4052799de22d350530f7ac557606dd09f6 Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 12:15:28 +0200 Subject: [PATCH 09/11] Move license link in menu --- docs/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index df0b24d..bd0b1c5 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -59,13 +59,13 @@ markdown_extensions: nav: - index.md + - license.md - Getting Started: - Installation: getting-started/installation.md - Run a VM: getting-started/vm.md - Deploy: getting-started/deploy.md - Development: - development/contributing.md - - license.md ## Section commented out below, would be autogenerated during docs rendering # - Reference: # - NixOS Module Options: From 8f378805f609b8127b437a99eead8fa116344e99 Mon Sep 17 00:00:00 2001 From: Andrea Ciceri Date: Tue, 30 Apr 2024 12:41:47 +0200 Subject: [PATCH 10/11] Minimal contributing page --- docs/development/contributing.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/development/contributing.md b/docs/development/contributing.md index 9d6cf4b..5020f61 100644 --- a/docs/development/contributing.md +++ b/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 😊 From 88a9b1246a657419246427aae85c3c7af0d1194e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rton=20Boros?= Date: Tue, 30 Apr 2024 15:00:55 +0000 Subject: [PATCH 11/11] fixes --- configurations/default.nix | 8 ++++++++ configurations/vm.nix | 26 ++++++++++++++++++-------- docs/getting-started/deploy.md | 8 +------- docs/getting-started/installation.md | 2 +- docs/getting-started/vm.md | 2 -- template/vm.nix | 24 ++++++++++++++++-------- 6 files changed, 44 insertions(+), 26 deletions(-) diff --git a/configurations/default.nix b/configurations/default.nix index 0be236a..511bc12 100644 --- a/configurations/default.nix +++ b/configurations/default.nix @@ -20,5 +20,13 @@ 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"; + } + ]; }; } diff --git a/configurations/vm.nix b/configurations/vm.nix index c2935c1..493f688 100644 --- a/configurations/vm.nix +++ b/configurations/vm.nix @@ -1,21 +1,31 @@ -{ - modulesPath, - lib, - pkgs, - ... -}: { +{modulesPath, ...}: { imports = [ (modulesPath + "/virtualisation/qemu-vm.nix") (modulesPath + "/profiles/qemu-guest.nix") ]; # WARNING: don't use this in production - # Allow root login without password - users.users.root.hashedPasswordFile = lib.mkOverride 150 "${pkgs.writeText "hashed-password.root" ""}"; + # 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; + } + ]; }; } diff --git a/docs/getting-started/deploy.md b/docs/getting-started/deploy.md index b83e7d7..080094a 100644 --- a/docs/getting-started/deploy.md +++ b/docs/getting-started/deploy.md @@ -1,5 +1,3 @@ -## Deploy Cardano services - 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 @@ -33,8 +31,4 @@ 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). - -Add these options to `configuration.nix` to - -### +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. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 00b0510..7262bf2 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,4 +1,4 @@ -## Requirements +### Requirements - linux - nix diff --git a/docs/getting-started/vm.md b/docs/getting-started/vm.md index efe1262..3ce5aae 100644 --- a/docs/getting-started/vm.md +++ b/docs/getting-started/vm.md @@ -1,5 +1,3 @@ -## Run Cardano services in a Virtual Machine - This project provides a virtual machine configuration with all cardano services. `nix run github:mlabs-haskell/cardano.nix#vm-preview` diff --git a/template/vm.nix b/template/vm.nix index c2935c1..b58c2ee 100644 --- a/template/vm.nix +++ b/template/vm.nix @@ -1,21 +1,29 @@ -{ - modulesPath, - lib, - pkgs, - ... -}: { +{modulesPath, ...}: { imports = [ (modulesPath + "/virtualisation/qemu-vm.nix") (modulesPath + "/profiles/qemu-guest.nix") ]; # WARNING: don't use this in production - # Allow root login without password - users.users.root.hashedPasswordFile = lib.mkOverride 150 "${pkgs.writeText "hashed-password.root" ""}"; + # 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"; + port = 3001; + } + { + # ogmios + from = "host"; + port = 1337; + } + ]; }; }