# NixOS

Configure the kogut server and agent with the NixOS module.

The flake's NixOS module runs the server, the agent, or both.

## Configure the server

Add the input and module to your flake:

```nix title="flake.nix"
{
  inputs.kogut.url = "github:piotrkowski/kogut";

  outputs = { nixpkgs, kogut, ... }: {
    nixosConfigurations.server = nixpkgs.lib.nixosSystem {
      modules = [
        kogut.nixosModules.default
        {
          services.kogut = {
            enable = true;
            url = "https://kogut.acme.com";
          };
        }
      ];
    };
  };
}
```

The module binds kogut to loopback and leaves the firewall closed. Add a reverse proxy:

```nix
services.caddy = {
  enable = true;
  virtualHosts."kogut.acme.com".extraConfig = "reverse_proxy 127.0.0.1:8484";
  virtualHosts."status.acme.com".extraConfig = "reverse_proxy 127.0.0.1:8484";
};
```

To listen on all IPv4 interfaces instead, set `services.kogut.listen = "0.0.0.0:8484"`,
and `services.kogut.openFirewall = true` to open that port.

Apply it with `sudo nixos-rebuild switch`, open the panel, and create your account with
the setup token from the journal:

```sh
journalctl -u kogut | grep setup_token
```

## Add checks and secrets

Put [`kogut.toml`](https://docs.kogut.dev/reference/configuration/) settings in `services.kogut.settings`.
Keep secrets in an environment file, not in the Nix store:

```nix
services.kogut = {
  environmentFile = "/run/secrets/kogut.env";
  settings = {
    brand.status_domain = "status.acme.com";
    check = [
      { name = "API"; url = "https://api.acme.com/health"; }
    ];
    alert = [
      {
        type = "telegram";
        bot_token = "\${TELEGRAM_BOT_TOKEN}";
        chat_id = "-1001234567890";
      }
    ];
  };
};
```

Write `TELEGRAM_BOT_TOKEN=...` in the environment file. The `\${...}` escape passes the
substitution to kogut as written. systemd `LoadCredential` also works for
[secret substitutions](https://docs.kogut.dev/reference/configuration/#secrets).

Rebuild after changing `settings`; the module writes a new file to the Nix store and
restarts the service.

## Configure the agent

```nix
services.kogut-agent = {
  enable = true;
  server = "https://kogut.acme.com";
  tokenFile = "/run/secrets/kogut-agent-token";
};
```

Use the token from **Hosts → Add a server**; the module loads it as a systemd
credential. It grants journal access, and Docker access when
`virtualisation.docker.enable` is set. Read
[Permissions and the Docker socket](https://docs.kogut.dev/agent/permissions/), or set
`services.kogut-agent.docker = false`.

Set other agent [environment variables](https://docs.kogut.dev/reference/environment-variables/#agent) in
`systemd.services.kogut-agent.environment`. All options are in
[the module](https://github.com/piotrkowski/kogut/blob/main/deploy/nix/module.nix).

The `kogut` package installs completions for bash, zsh, and fish.

## Update

Follow [Upgrading](https://docs.kogut.dev/installation/upgrading/). If the flake input points to a release tag, change the
tag first.