infrastructure/README.md

<!--
SPDX-FileCopyrightText: 2024 Maurice Debray <maurice.debray@dgnum.eu>
SPDX-FileCopyrightText: 2024 Tom Hubrecht <tom.hubrecht@dgnum.eu>

SPDX-License-Identifier: EUPL-1.2
-->

# ❄️ infrastructure

The dgnum infrastructure.

# Contributing

Some instruction on how to contribute are available (in french) in [/CONTRIBUTE.md](CONTRIBUTE.md).
You're expected to read this document before commiting to the repo.

Some documentation for the development tools are provided in the aforementioned file.

# Using the binary cache

Add the following module to your configuration (and pin this repo using your favorite tool: npins, lon, etc...):
```
{ lib, ... }:
let
  dgnum-infra = PINNED_PATH_TO_INFRA;
in {
  nix.settings = (import dgnum-infra { }).mkCacheSettings {
    caches = [ "infra" ];
  };
}
```


# Adding a new machine

The first step is to create a minimal viable NixOS host, using tha means necessary.
The second step is to find a name for this host, it must be unique from the other hosts.

> [!TIP]
> For the rest of this part, we assume that the host is named `host02`

## Download the keys

The public SSH keys of `host02` have to be saved to `keys`, preferably only the `ssh-ed25519` one.

It can be retreived with :

```bash
ssh-keyscan address.of.host02 2>/dev/null | awk '/ssh-ed25519/ {print $2,$3}'
```

## Initialize the machine folder and configuration

- Create a folder `host02` under `machines/`
- Copy the hardware configuration file generated by `nixos-generate-config` to `machines/host02/_hardware-configuration.nix`
- Create a `machines/host02/_configuration.nix` file, it will contain the main configuration options, the basic content of this file should be the following

```nix
{ lib, ... }:

lib.extra.mkConfig {
  enabledModules = [
    # List of modules to enable
  ];

  enabledServices = [
    # List of services to enable
  ];

  extraConfig = {
    services.netbird.enable = true;
  };

  root = ./.;
}
```

## Fill in the metadata

### Network configuration

The network is declared in `meta/network.nix`, the necessary `hostId` value can be generated with :

```bash
head -c4 /dev/urandom | od -A none -t x4 | sed 's/ //'
```

### Other details

The general metadata is declared in `meta/nodes.nix`, the main values to declare are :

- `site`, where the node is physically located
- `stateVersion`
- `nixpkgs`, the nixpkgs version to use

## Initialize secrets

Create the directory `secrets` in the configuration folder, and add a `secrets.nix` file containing :

```nix
(import ../../../keys).mkSecrets [ "host02" ] [
  # List of secrets for host02
]
```

This will be used for future secret management.

## Update encrypted files

Both the Arkheon, Netbox and notification modules have secrets that are deployed on all machines. To make those services work correctly, run in `modules/dgn-records`, `modules/dgn-netbox-agent` and `modules/dgn-notify` :

```bash
agenix -r
```

## Commit and create a PR

Once all of this is done, check that the configuration builds correctly :

```bash
colmena build --on host02
```

Apply it, and create a Pull Request.