From 8264c7ccb1f9566c3e17b45747dd35736c766be1 Mon Sep 17 00:00:00 2001
From: Valentin <valentin@fricklerhandwerk.de>
Date: Tue, 14 Oct 2025 14:34:11 +0200
Subject: Einrichtung des ersten Servers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Das System kann mit einem Befehl beim Hosting-Provider aufgesetzt werden.
Es bietet zunächst nur einem SSH-Zugang für Administratoren.
---
 README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d60f3dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,102 @@
+# 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
+
+### 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/).
+
+Angenommen, in `~/.ssh/config` ist Folgendes eingetragen:
+
+```
+Host tharos
+  ForwardAgent yes
+  HostName 81.169.239.254
+  IdentityFile /home/user/.ssh/tharos
+```
+
+Dann kann man sich mit dem Produktionssystem über SSH verbinden:
+
+```bash
+ssh tharos
+```
+
+### Geänderte Konfiguration anwenden
+
+```bash
+nix run .#deploy-tharos -- switch
+```
+
+## 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).
+
+Nutzernamen von Administratoren und ihre SSH-Keys sind unter [`keys`](./keys) organisiert.
+
+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.
-- 
cgit v1.2.3