# IT-Infrastruktur für den Stadtteilbeirat Heimfeld

Dieses Git-Repository enthält den Quellcode für Konfiguration und Verwaltung von Rechnern, welche Dienste unter der DNS-Domain `heimfeld.hamburg` bereitstellen.

## Vorbereitung

Um mit dem Code zu arbeiten, zunächst Nix installieren:

- Debian/Ubuntu

  ```bash
  apt install --yes curl git jq nix
  ```

- Arch

  ```bash
  pacman --sync --refresh --noconfirm curl git jq nix
  ```

Anschließend Flakes aktivieren:

```bash
echo extra-experimental-features = nix-command flakes >> /etc/nix/nix.conf
```

Beim ersten Aufruf von `nix run` oder `nix flake check` werden Abhängigkeiten geladen oder gebaut, was eine Weile dauern kann.
Spätere Aufrufe sind viel schneller, da nur Änderungen verarbeitet werden müssen.

## Abläufe

### Quellcode abrufen

```bash
git clone https://git.heimfeld.hamburg/infra
```

Weitere URLs (z.B. für SSH) sind zu finden auf <https://git.heimfeld.hamburg/infra/> unter **Clone**.

### SSH einrichten

Folgendes in `~/.ssh/config` eintragen:

```
Host tharos
  ForwardAgent yes
  HostName 81.169.239.254
  IdentityFile /home/<user>/.ssh/tharos
```

wobei `<user>` das eigene lokale Linux-Benutzerkonto ist.

### Administrator hinzufügen

Nutzernamen von Administratoren und ihre SSH-Keys sind unter [`keys`](./keys) organisiert.
Das Format des Ordners ist in [`keys.nix`](./keys.nix) dokumentiert.


Sich selbst als Administrator mit genau einem SSH-Schlüssel hinzuzufügen:

```bash
cat ~/.ssh/foo.pub > ./keys/$USER
```

Sich selbst als Administrator mit mehreren Schlüsseln hinzuzufügen:

```bash
mkdir .keys/$USER
cp ~/.ssh/foo.pub > ./keys/$USER/
cp ~/.ssh/bar.pub > ./keys/$USER/
```

### Änderungen am Quellcode hochladen

Auf dem Server muss ein [SSH Public Key für den hochlandenden Nutzer](#administrator-hinzufugen) von einem Administrator eingerichtet worden sein.

[Erstmalig wurde der Quellcode über HTTPS abgerufen](#quellcode-abrufen), daher muss `remotes` angepasst werden:

```bash
git remote set-url origin ssh://heimfeld.hamburg/git/infra
```

Da mehrere Nutzer Schreibzugriff auf das Repository haben, muss jeder Nutzer explizit den eigenen Zugriff mit [`safe.directory`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-safedirectory) erlauben:

```bash
ssh tharos git config --global --add safe.directory /git/infra
```

Dann wie üblich:

```bash
git push origin main
```

### Tests durchführen

```bash
nix flake check
```

### Konfiguration lokal ausprobieren

```bash
nix run .#vm-tharos
```

Dieser Befehl startet eine virtuelle Maschine mit der exakten Konfiguration des Produktionssystems.

Anschließend kann man sich über SSH mit dem auf der Maschine eingerichteten Nutzer und dem entsprechenden SSH-Key verbinden:

```bash
ssh localhost -p 10022 -o ForwardAgent=yes -i ~/.ssh/tharos
```

Der SSH-Port ist entsprechend der VM-Konfiguration versetzt um Konflikte mit möglicherweise bestehenden Diensten auf dem Host zu vermeiten.
`ForwardAgent=yes` ist erforderlich, um Befehle mit `sudo` auszuführen, wobei die Authentifizierung über direkt SSH statt einem Passwort erfolgt.

### Eine neue Maschine aufsetzen

**ACHTUNG: Alle Daten auf dem Zielsystem werden dabei gelöscht!**

```bash
nix run .#infect-tharos
```

Die NixOS-Installation erfolgt mit [`nixos-anywhere`](https://nix-community.github.io/nixos-anywhere/).

Mit dem laufenden Produktionssystem über SSH verbinden:

```bash
ssh tharos
```

### Geänderte Konfiguration anwenden

```bash
nix run .#deploy-tharos -- switch
```

### Systemüberwachung und Statistiken

Alle Metriken werden gesammelt und dargestellt auf <https://grafana.heimfeld.hamburg>.

Dashboards werden deklarativ verwaltet in [tharos/dashboards](./tharos/dashboards).

Grafische Bearbeitung ist möglich [in der virtuellen Maschine](#konfiguration-lokal-ausprobieren).
Danach muss die JSON-Konfiguration exportiert und von Hand auf das Wesentliche reduziert werden.

## Architektur

Die Systeme laufen auf NixOS und werden mit Nix verwaltet.

Dokumentation zu beiden ist zu finden unter <https://nix.dev>.
Die wesentlichen Aspekte sind dort die [Nix-Sprache](https://nix.dev/tutorials/nix-language) und das [Modulsystem](https://nix.dev/tutorials/module-system/).

Der Code hier ist modular organisiert mit Flake Parts, was es einfacher macht isolierte Änderungen vorzunehmen und die Lesbarkeit verbessern hilft.
Flake Parts sind dokumentiert unter <https://flake.parts>.

Zusätzlich wird mit `flakes.machines` eine eigene Abstraktion verwendet um Systeme und entsprechende Hilfswerkzeuge zu konfigurieren.
Dies ist momentan nur im Quellcode dokumentiert in [`machines.nix`](./machines.nix).

Zur Zeit ist genau eine Maschine in Betrieb, die in [`tharos.nix`](./tharos.nix) spezifiziert ist.
Der Server läuft bei [STRATO](https://www.strato.de) unter Kundennummer 73292174, Auftragsnummer 7709638.