Fediversity/deployment/README.md

# Deployment

This directory contains work to generate a full Fediversity deployment from a minimal configuration.
This is different from [`../services/`](../services) that focuses on one machine, providing a polished and unified interface to different Fediverse services.

## Checks

There are three levels of deployment checks: `basic`, `cli`, `panel`.
They can be found in subdirectories of [`check/`](./check).
They can be run as part of `nix flake check` or individually as:

``` console
$ nix build .#checks.<system>.deployment-<name> -vL
```

Since `nixops4 apply` operates on a flake, the tests take this repository's flake as a template.
This also why there are some dummy files that will be overwritten inside the test.

### Basic deployment check

The basic deployment check is here as a building block and sanity check.
It does not actually use any of the code in this directory but checks that our test strategy is sound and that basic NixOps4 functionalities are here.

It is a NixOS test featuring one deployer machine and two target machines.
The deployment simply adds `pkgs.hello` to one and `pkgs.cowsay` to the other.
It is heavily inspired by [a similar test in `nixops4-nixos`].

[a similar test in nixops4-nixos]: https://github.com/nixops4/nixops4-nixos/blob/main/test/default/nixosTest.nix

This test involves three nodes:

- `deployer` is the node that will perform the deployment using `nixops4 apply`.
  Because the test runs in a sandboxed environment, `deployer` will not have access to internet, and therefore it must already have all store paths needed for the target nodes.

- “target machines” are two eponymous nodes on which the packages `hello` and `cowsay` will be deployed.
  They start with a minimal configuration.

``` mermaid
flowchart LR
  deployer["deployer<br><font size='1'>has store paths<br>runs nixops4</font>"]

  subgraph target_machines["target machines"]
    direction TB
    hello
    cowsay
  end

  deployer -->|deploys| target_machines
```

### Service deployment check using `nixops4 apply`

This check omits the panel by running a direct invocation of NixOps4.
It deploys some services and checks that they are indeed on the target machines, then cleans them up and checks whether that works, too.
It builds upon the basic deployment check.

This test involves seven nodes:

- `deployer` is the node that will perform the deployment using `nixops4 apply`.
  Because the test runs in a sandboxed environment, `deployer` will not have access to internet, and therefore it must already have all store paths needed for the target nodes.

- “target machines” are four nodes — `garage`, `mastodon`, `peertube`, and `pixelfed` — on which the services will be deployed.
  They start with a minimal configuration.

- `acme` is a node that runs [Pebble], a miniature ACME server to deliver the certificates that the services expect.

- [WIP] `client` is a node that runs a browser controlled by some Selenium scripts in order to check that the services are indeed running and are accessible.

[Pebble]: https://github.com/letsencrypt/pebble

``` mermaid
flowchart LR

  classDef invisible fill:none,stroke:none

  subgraph left [" "]
    direction TB

    deployer["deployer<br><font size='1'>has store paths<br>runs nixops4</font>"]
    client["client<br><font size='1'>Selenium scripts</font>"]
  end

  subgraph middle [" "]
    subgraph target_machines["target machines"]
      direction TB

      garage
      mastodon
      peertube
      pixelfed
    end
  end

  subgraph right [" "]
    direction TB

    acme["acme<br><font size='1'>runs Pebble</font>"]
  end

  left ~~~ middle ~~~ right
  class left,middle,right invisible

  deployer -->|deploys| target_machines

  client -->|tests| mastodon
  client -->|tests| peertube
  client -->|tests| pixelfed

  target_machines -->|get certs| acme
```

### [WIP] Service deployment check from the panel

This is a full deployment check running the panel on the deployer machine, deploying some services through the panel and checking that they are indeed on the target machines, then cleans them up and checks whether that works, too.

It builds upon the basic and CLI deployment checks.