~stepbrobd/ngipkgs

43150a5580e88278882339ea9f5f53a2f6420f6a — Cleeyv a month ago e40efee
Document how to deploy NGIpkgs services (#369)

* Init deploy dir with README docs

Co-authored-by: Valentin Gagarin <valentin@gagarin.work>
4 files changed, 495 insertions(+), 0 deletions(-)

A deploy/README.md
A deploy/configuration.nix
A deploy/flake.lock
A deploy/flake.nix
A deploy/README.md => deploy/README.md +69 -0
@@ 0,0 1,69 @@
# How to install software from NGIpkgs

Installation of software from NGIpkgs currently requires Nix [flakes to be enabled](https://wiki.nixos.org/wiki/Flakes).

##  Run a **standalone program** locally with Nix

```
nix run github:ngi-nix/ngipkgs#atomic-cli
```

This example uses [`atomic-cli`](https://atomicserver.eu/cli/README.html), but the same can be done with any packages from NGIpkgs that is designed to be run as a standalone program.
The list of these packages can be generated by running the following command inside a downloaded copy of the NGIpkgs repository:
```
grep -r mainProgram pkgs/by-name
```

## Deploy **services** to machines running NixOS

1. Download a local copy of the NGIpkgs repository to use it to deploy services:
```
git clone https://github.com/ngi-nix/ngipkgs.git
```

2. There is a `deploy` directory within `ngipkgs` that is set up for easy deployment of services.
   Enter this directory and edit the `flake.nix` there to enable a service by removing comments from its module and example configuration.
   For example, this would enable the Kbin service:
```
modules = [
  [...]
  ### VULA
  # ngipkgs.nixosModules."services.vula"
  # ./Vula/example-simple.nix
  ###
  ### KBIN
  ngipkgs.nixosModules."services.kbin"
  ./Kbin/example.nix
  ###
  ### PEERTUBE
  # ngipkgs.nixosModules."services.peertube.plugins"
  # ./PeerTube/example.nix
  ###
  [...]
  ];
```

3. Still inside of the `deploy` directory, run the following commands to build and deploy a local QEMU VM running the enabled service:
   ```
   nix build .#nixosConfigurations.myMachine.config.system.build.vm && export QEMU_NET_OPTS="hostfwd=tcp::2221-:22,hostfwd=tcp::8080-:80" && ./result/bin/run-nixos-vm
   ```

   QEMU will open its own terminal window that shows the boot log.
   It is possible to login via this terminal (username `user`, password `pass`), but it is more convenient when logging in through SSH:

   ```
   ssh -oUserKnownHostsFile=/dev/null -oStrictHostKeyChecking=no user@localhost -p 2221
   ```

### Services available for deployment

An up to date list of services with example configurations that are ready to be deployed can be found by running this command in the main directory of the NGIpkgs repository:
```
find ./projects -type f -name 'example*.nix'
```

There is also a longer list of services that have working tests (or more complex examples) which can be adapted to get a working deployment.
To view a list of these services, run the following command in the main directory of the NGIpkgs repo:
```
find ./projects -name 'test*'
```

A deploy/configuration.nix => deploy/configuration.nix +23 -0
@@ 0,0 1,23 @@
{
  config,
  pkgs,
  ...
}: {
  # For more info: https://github.com/ngi-nix/ngipkgs/blob/main/maintainers/cachix.md
  nix.settings.substituters = ["https://ngi.cachix.org/"];
  nix.settings.trusted-public-keys = ["ngi.cachix.org-1:n+CAL72ROC3qQuLxIHpV+Tw5t42WhXmMhprAGkRSrOw="];

  users.users.user = {
    isNormalUser = true;
    extraGroups = ["wheel"];
    initialPassword = "pass";
  };

  services.openssh = {
    enable = true;
    settings.PasswordAuthentication = true;
  };
  networking.firewall.allowedTCPPorts = [22];

  system.stateVersion = "24.11";
}

A deploy/flake.lock => deploy/flake.lock +364 -0
@@ 0,0 1,364 @@
{
  "nodes": {
    "buildbot-nix": {
      "inputs": {
        "flake-parts": "flake-parts",
        "nixpkgs": [
          "ngipkgs",
          "nixpkgs"
        ],
        "treefmt-nix": "treefmt-nix"
      },
      "locked": {
        "lastModified": 1727098656,
        "narHash": "sha256-YzzqDIR+nuB+JsiQ7BTMuXzHe06vnFw/+AEo6en/hx4=",
        "owner": "nix-community",
        "repo": "buildbot-nix",
        "rev": "3ac54ba1cc53aae01dd27055a710fbebab19acfe",
        "type": "github"
      },
      "original": {
        "owner": "nix-community",
        "repo": "buildbot-nix",
        "type": "github"
      }
    },
    "dream2nix": {
      "inputs": {
        "nixpkgs": [
          "ngipkgs",
          "nixpkgs"
        ],
        "purescript-overlay": "purescript-overlay",
        "pyproject-nix": "pyproject-nix"
      },
      "locked": {
        "lastModified": 1726523340,
        "narHash": "sha256-Av5mdR2lAGUVdA6DJ8Anon3/FZg3DX4gl1Ff72rCpKU=",
        "owner": "nix-community",
        "repo": "dream2nix",
        "rev": "b76c529f377100516c40c5b6e239a4525fdcabe0",
        "type": "github"
      },
      "original": {
        "owner": "nix-community",
        "repo": "dream2nix",
        "type": "github"
      }
    },
    "flake-compat": {
      "flake": false,
      "locked": {
        "lastModified": 1696426674,
        "narHash": "sha256-kvjfFW7WAETZlt09AgDn1MrtKzP7t90Vf7vypd3OL1U=",
        "owner": "edolstra",
        "repo": "flake-compat",
        "rev": "0f9255e01c2351cc7d116c072cb317785dd33b33",
        "type": "github"
      },
      "original": {
        "owner": "edolstra",
        "repo": "flake-compat",
        "type": "github"
      }
    },
    "flake-parts": {
      "inputs": {
        "nixpkgs-lib": [
          "ngipkgs",
          "buildbot-nix",
          "nixpkgs"
        ]
      },
      "locked": {
        "lastModified": 1726153070,
        "narHash": "sha256-HO4zgY0ekfwO5bX0QH/3kJ/h4KvUDFZg8YpkNwIbg1U=",
        "owner": "hercules-ci",
        "repo": "flake-parts",
        "rev": "bcef6817a8b2aa20a5a6dbb19b43e63c5bf8619a",
        "type": "github"
      },
      "original": {
        "owner": "hercules-ci",
        "repo": "flake-parts",
        "type": "github"
      }
    },
    "flake-utils": {
      "inputs": {
        "systems": [
          "ngipkgs",
          "systems"
        ]
      },
      "locked": {
        "lastModified": 1726560853,
        "narHash": "sha256-X6rJYSESBVr3hBoH0WbKE5KvhPU5bloyZ2L4K60/fPQ=",
        "owner": "numtide",
        "repo": "flake-utils",
        "rev": "c1dfcf08411b08f6b8615f7d8971a2bfa81d5e8a",
        "type": "github"
      },
      "original": {
        "owner": "numtide",
        "repo": "flake-utils",
        "type": "github"
      }
    },
    "gitignore": {
      "inputs": {
        "nixpkgs": [
          "ngipkgs",
          "pre-commit-hooks",
          "nixpkgs"
        ]
      },
      "locked": {
        "lastModified": 1709087332,
        "narHash": "sha256-HG2cCnktfHsKV0s4XW83gU3F57gaTljL9KNSuG6bnQs=",
        "owner": "hercules-ci",
        "repo": "gitignore.nix",
        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
        "type": "github"
      },
      "original": {
        "owner": "hercules-ci",
        "repo": "gitignore.nix",
        "type": "github"
      }
    },
    "ngipkgs": {
      "inputs": {
        "buildbot-nix": "buildbot-nix",
        "dream2nix": "dream2nix",
        "flake-utils": "flake-utils",
        "nixpkgs": "nixpkgs",
        "nixpkgs-stable": "nixpkgs-stable",
        "pre-commit-hooks": "pre-commit-hooks",
        "sops-nix": "sops-nix",
        "systems": "systems"
      },
      "locked": {
        "lastModified": 1727105170,
        "narHash": "sha256-nvKaACwBmZ5dDSD0FqSNRGwlNvW64a4qRWw17drhUog=",
        "owner": "ngi-nix",
        "repo": "ngipkgs",
        "rev": "66ff2de8e1249499b8abfa15a86baa53fedb2e72",
        "type": "github"
      },
      "original": {
        "owner": "ngi-nix",
        "repo": "ngipkgs",
        "type": "github"
      }
    },
    "nixpkgs": {
      "locked": {
        "lastModified": 1726871744,
        "narHash": "sha256-V5LpfdHyQkUF7RfOaDPrZDP+oqz88lTJrMT1+stXNwo=",
        "owner": "NixOS",
        "repo": "nixpkgs",
        "rev": "a1d92660c6b3b7c26fb883500a80ea9d33321be2",
        "type": "github"
      },
      "original": {
        "owner": "NixOS",
        "ref": "nixpkgs-unstable",
        "repo": "nixpkgs",
        "type": "github"
      }
    },
    "nixpkgs-stable": {
      "locked": {
        "lastModified": 1720535198,
        "narHash": "sha256-zwVvxrdIzralnSbcpghA92tWu2DV2lwv89xZc8MTrbg=",
        "owner": "NixOS",
        "repo": "nixpkgs",
        "rev": "205fd4226592cc83fd4c0885a3e4c9c400efabb5",
        "type": "github"
      },
      "original": {
        "owner": "NixOS",
        "ref": "nixos-23.11",
        "repo": "nixpkgs",
        "type": "github"
      }
    },
    "nixpkgs_2": {
      "locked": {
        "lastModified": 1726937504,
        "narHash": "sha256-bvGoiQBvponpZh8ClUcmJ6QnsNKw0EMrCQJARK3bI1c=",
        "owner": "nixos",
        "repo": "nixpkgs",
        "rev": "9357f4f23713673f310988025d9dc261c20e70c6",
        "type": "github"
      },
      "original": {
        "owner": "nixos",
        "ref": "nixos-unstable",
        "repo": "nixpkgs",
        "type": "github"
      }
    },
    "pre-commit-hooks": {
      "inputs": {
        "flake-compat": "flake-compat",
        "gitignore": "gitignore",
        "nixpkgs": [
          "ngipkgs",
          "nixpkgs"
        ],
        "nixpkgs-stable": [
          "ngipkgs",
          "nixpkgs-stable"
        ]
      },
      "locked": {
        "lastModified": 1726745158,
        "narHash": "sha256-D5AegvGoEjt4rkKedmxlSEmC+nNLMBPWFxvmYnVLhjk=",
        "owner": "cachix",
        "repo": "pre-commit-hooks.nix",
        "rev": "4e743a6920eab45e8ba0fbe49dc459f1423a4b74",
        "type": "github"
      },
      "original": {
        "owner": "cachix",
        "repo": "pre-commit-hooks.nix",
        "type": "github"
      }
    },
    "purescript-overlay": {
      "inputs": {
        "nixpkgs": [
          "ngipkgs",
          "dream2nix",
          "nixpkgs"
        ],
        "slimlock": "slimlock"
      },
      "locked": {
        "lastModified": 1696022621,
        "narHash": "sha256-eMjFmsj2G1E0Q5XiibUNgFjTiSz0GxIeSSzzVdoN730=",
        "owner": "thomashoneyman",
        "repo": "purescript-overlay",
        "rev": "047c7933abd6da8aa239904422e22d190ce55ead",
        "type": "github"
      },
      "original": {
        "owner": "thomashoneyman",
        "repo": "purescript-overlay",
        "type": "github"
      }
    },
    "pyproject-nix": {
      "flake": false,
      "locked": {
        "lastModified": 1702448246,
        "narHash": "sha256-hFg5s/hoJFv7tDpiGvEvXP0UfFvFEDgTdyHIjDVHu1I=",
        "owner": "davhau",
        "repo": "pyproject.nix",
        "rev": "5a06a2697b228c04dd2f35659b4b659ca74f7aeb",
        "type": "github"
      },
      "original": {
        "owner": "davhau",
        "ref": "dream2nix",
        "repo": "pyproject.nix",
        "type": "github"
      }
    },
    "root": {
      "inputs": {
        "ngipkgs": "ngipkgs",
        "nixpkgs": "nixpkgs_2"
      }
    },
    "slimlock": {
      "inputs": {
        "nixpkgs": [
          "ngipkgs",
          "dream2nix",
          "purescript-overlay",
          "nixpkgs"
        ]
      },
      "locked": {
        "lastModified": 1688610262,
        "narHash": "sha256-Wg0ViDotFWGWqKIQzyYCgayeH8s4U1OZcTiWTQYdAp4=",
        "owner": "thomashoneyman",
        "repo": "slimlock",
        "rev": "b5c6cdcaf636ebbebd0a1f32520929394493f1a6",
        "type": "github"
      },
      "original": {
        "owner": "thomashoneyman",
        "repo": "slimlock",
        "type": "github"
      }
    },
    "sops-nix": {
      "inputs": {
        "nixpkgs": [
          "ngipkgs",
          "nixpkgs"
        ],
        "nixpkgs-stable": [
          "ngipkgs",
          "nixpkgs-stable"
        ]
      },
      "locked": {
        "lastModified": 1726524647,
        "narHash": "sha256-qis6BtOOBBEAfUl7FMHqqTwRLB61OL5OFzIsOmRz2J4=",
        "owner": "Mic92",
        "repo": "sops-nix",
        "rev": "e2d404a7ea599a013189aa42947f66cede0645c8",
        "type": "github"
      },
      "original": {
        "owner": "Mic92",
        "repo": "sops-nix",
        "type": "github"
      }
    },
    "systems": {
      "locked": {
        "lastModified": 1689347949,
        "narHash": "sha256-12tWmuL2zgBgZkdoB6qXZsgJEH9LR3oUgpaQq2RbI80=",
        "owner": "nix-systems",
        "repo": "default-linux",
        "rev": "31732fcf5e8fea42e59c2488ad31a0e651500f68",
        "type": "github"
      },
      "original": {
        "owner": "nix-systems",
        "repo": "default-linux",
        "type": "github"
      }
    },
    "treefmt-nix": {
      "inputs": {
        "nixpkgs": [
          "ngipkgs",
          "buildbot-nix",
          "nixpkgs"
        ]
      },
      "locked": {
        "lastModified": 1726734507,
        "narHash": "sha256-VUH5O5AcOSxb0uL/m34dDkxFKP6WLQ6y4I1B4+N3L2w=",
        "owner": "numtide",
        "repo": "treefmt-nix",
        "rev": "ee41a466c2255a3abe6bc50fc6be927cdee57a9f",
        "type": "github"
      },
      "original": {
        "owner": "numtide",
        "repo": "treefmt-nix",
        "type": "github"
      }
    }
  },
  "root": "root",
  "version": 7
}

A deploy/flake.nix => deploy/flake.nix +39 -0
@@ 0,0 1,39 @@
{
  description = "An example deployment of NGIpkgs software to a local VM";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    ngipkgs.url = "github:ngi-nix/ngipkgs";
  };

  outputs = {
    self,
    nixpkgs,
    ngipkgs,
  }: {
    nixosConfigurations.myMachine = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        ngipkgs.nixosModules.default

        ### VULA
        # ngipkgs.nixosModules."services.vula"
        # ../projects/Vula/example-simple.nix
        ###
        ### KBIN
        # ngipkgs.nixosModules."services.kbin"
        # ../projects/Kbin/example.nix
        ###
        ### PEERTUBE
        # ngipkgs.nixosModules."services.peertube"
        # ../projects/PeerTube/example.nix
        ###
        ### ATOMICDATA
        # ngipkgs.nixosModules."services.atomic-server"
        # ../projects/AtomicData/example.nix
        ###
      ];
    };
  };
}