README.md.de

# lmndev-runner

Docker-basierte Build-Umgebung für [linuxmuster.net](https://linuxmuster.net) Debian-Pakete.

Das Image kann sowohl als Container in einem **GitHub Actions Workflow** als auch als
**lokales Buildsystem** auf einem Linux-Rechner eingesetzt werden.

---

## Inhaltsverzeichnis

1. [Voraussetzungen](#voraussetzungen)
2. [Verzeichnisstruktur](#verzeichnisstruktur)
3. [Konfiguration](#konfiguration)
4. [Images bauen](#images-bauen)
5. [Lokale Nutzung](#lokale-nutzung)
6. [Nutzung als GitHub Actions Runner](#nutzung-als-github-actions-runner)
7. [Release-Workflows](#release-workflows)
8. [Pro-Projekt-Buildskripte](#pro-projekt-buildskripte)
9. [Image veröffentlichen (GHCR)](#image-veröffentlichen-ghcr)

---

## Voraussetzungen

Für den **lokalen Betrieb** werden benötigt:

- Docker
- `bash`, `curl`, `python3` (für `collect-deps.sh` und `build.sh`)
- Internetzugang (GitHub API, Ubuntu-Paketquellen)

Für den **GitHub Actions Betrieb** sind keine lokalen Voraussetzungen nötig — das
Image wird von der GHCR bezogen.

---

## Verzeichnisstruktur

```text
lmndev-runner/
├── config                        # Zentrale Konfiguration
├── Dockerfile                    # Image-Definition
├── build.sh                      # Lokaler Image-Build
├── collect-deps.sh               # Sammelt Build-Abhängigkeiten, lädt linuxmuster-common
├── start.sh                      # Startet Container interaktiv (lokales oder Remote-Image)
├── ghcr-start.sh                 # Kompatibilitäts-Wrapper: entspricht ./start.sh --remote
├── build/                        # Pro-Projekt-Buildskripte (im Image unter /opt/lmndev/build/)
│   ├── common.sh                 # Gemeinsame Build-Funktionen
│   ├── linuxmuster-api.sh
│   ├── linuxmuster-base7.sh
│   ├── linuxmuster-cli7.sh
│   ├── linuxmuster-common.sh
│   ├── linuxmuster-fileserver.sh
│   ├── linuxmuster-linbo7.sh
│   ├── linuxmuster-linbo-gui.sh
│   ├── linuxmuster-linuxclient7.sh
│   ├── linuxmuster-prepare.sh
│   ├── linuxmuster-tools.sh
│   ├── linuxmuster-webui7.sh
│   └── sophomorix4.sh
├── workflows/                    # Beispiel-Release-Workflows für Projekt-Repositories
│   ├── linuxmuster-api.release.yml
│   ├── linuxmuster-base7.release.yml
│   └── ...                       # je ein .release.yml pro Projekt
└── .github/workflows/
    └── build-push.yml            # Baut und pusht das Image selbst zu GHCR
```

---

## Konfiguration

Alle Einstellungen befinden sich in der Datei `config`. Sie wird von `build.sh`,
`collect-deps.sh` und `start.sh` eingelesen.

```sh
# Ubuntu-Versionen
UBUNTU_VERSION="26.04"          # primäre Version (bekommt zusätzlich den :latest-Tag)
UBUNTU_FALLBACK="24.04"         # Fallback, wenn die primäre Version nicht verfügbar ist
UBUNTU_VERSIONS="24.04 26.04"   # alle unterstützten Versionen (für ./build.sh all)

# Docker Image-Namen
IMAGE_NAME="lmndev-runner"
GHCR_IMAGE="ghcr.io/linuxmuster/lmndev-runner"

# Standard-Shell im Container: bash | zsh | ash | fish
DEFAULT_SHELL="bash"

# Zusätzliche Pakete nur für die lokale Nutzung (für GitHub Actions leer lassen)
EXTRA_PACKAGES=""

# Build-User im Container
MY_USER="build"
MY_UID="1000"
MY_GID="1000"

# Unterstützte Projekte (leerzeichen-getrennt)
PROJECTS="linuxmuster-api linuxmuster-base7 ..."
```

### Konfigurierbare Parameter im Überblick

| Parameter | Beschreibung | Standard |
| --- | --- | --- |
| `UBUNTU_VERSION` | Primäre Ubuntu-Version (bekommt auch den `:latest`-Tag) | `26.04` |
| `UBUNTU_FALLBACK` | Fallback-Version, wenn primäre nicht verfügbar | `24.04` |
| `UBUNTU_VERSIONS` | Alle Versionen, die `./build.sh all` baut | `24.04 26.04` |
| `DEFAULT_SHELL` | Standard-Shell beim Start von `start.sh` | `bash` |
| `EXTRA_PACKAGES` | Überschreibt die Standard-Extrapakete des Dockerfiles | *(leer = Dockerfile-Standard wird genutzt)* |
| `MY_UID` / `MY_GID` | UID/GID des Build-Users | `1000` / `1000` |
| `PROJECTS` | Zu unterstützende Projekte | alle 12 Projekte |

### EXTRA_PACKAGES

Das Dockerfile enthält bereits einen sinnvollen Satz an Standard-Extrapaketen:

```text
openssh-client iputils-ping net-tools wget bash bash-completion zsh
zsh-autosuggestions zsh-syntax-highlighting ccache distcc curl
dpkg-dev debdelta sudo vim git
```

Bleibt `EXTRA_PACKAGES` in `config` leer, werden diese Dockerfile-Standards verwendet.
Ist `EXTRA_PACKAGES` in `config` gesetzt, **ersetzt** es die Dockerfile-Standards vollständig.

### Shell-Optionen

Alle vier Shells sind **immer** im Image installiert — unabhängig von der Konfiguration.
Die gewünschte Shell wird erst zur Laufzeit ausgewählt.

| Wert | Paket | Shell-Pfad |
| --- | --- | --- |
| `bash` | `bash` | `/bin/bash` |
| `zsh` | `zsh` | `/bin/zsh` |
| `ash` | `busybox` | `/bin/ash` |
| `fish` | `fish` | `/usr/bin/fish` |

### Projekte anpassen

Sollen nur bestimmte Projekte unterstützt werden, `PROJECTS` in `config` entsprechend
kürzen. Die Build-Abhängigkeiten werden dann nur für die gelisteten Projekte gesammelt,
was die Image-Größe reduziert.

---

## Images bauen

Images werden pro Ubuntu-Version gebaut und entsprechend getaggt: `:24.04`, `:26.04`.
Die primäre Version (aktuell `26.04`) erhält zusätzlich den Tag `:latest`.

### Primäre Version bauen (Standard)

```sh
./build.sh
```

### Bestimmte Version bauen

```sh
./build.sh 24.04
./build.sh 26.04
```

### Alle Versionen auf einmal bauen

```sh
./build.sh all
```

`collect-deps.sh` wird dabei nur einmal aufgerufen und das Ergebnis für alle Versionen verwendet.

### Dependency-Sammlung überspringen (vorhandene Dateien verwenden)

Wenn `deps.txt` und `linuxmuster-common.deb` bereits vorhanden sind (z. B. nach einem
fehlgeschlagenen Build), kann der Download-Schritt übersprungen werden:

```sh
./build.sh --no-collect
./build.sh --no-collect 24.04
./build.sh --no-collect all
```

### Was `build.sh` ausführt

1. **Zu bauende Versionen ermitteln** anhand des Arguments (`24.04`, `26.04`, `all` oder Standard).
2. **`collect-deps.sh` aufrufen** — holt für jedes konfigurierte Projekt die Datei
   `debian/control` von GitHub und extrahiert alle `Build-Depends`-Felder. Die
   deduplizierte Paketliste wird in `deps.txt` geschrieben.
3. **Neuestes `linuxmuster-common` herunterladen** — das aktuellste `.deb`-Paket wird
   über die GitHub Releases API ermittelt und lokal gespeichert.
4. **`docker build` für jede Version ausführen** — das Image wird als `IMAGE_NAME:VERSION`
   getaggt (für die primäre Version zusätzlich als `:latest`). Temporäre Dateien werden
   danach automatisch gelöscht.

### Wie `collect-deps.sh` funktioniert

Das Skript lädt für jedes Projekt in `PROJECTS` die Datei `debian/control` direkt von
GitHub:

```text
https://raw.githubusercontent.com/linuxmuster/PROJEKT/main/debian/control
```

Aus dem `Build-Depends`-Feld werden alle Paketnamen extrahiert. Dabei werden:

- Versionsbeschränkungen (z. B. `debhelper (>= 10)`) entfernt
- Alternativen (`paket-a | paket-b`) auf die erste Option reduziert
- `linuxmuster-*`-Pakete ausgeschlossen (werden separat installiert)
- Duplikate entfernt

Das Paket `linuxmuster-common` wird separat über die GitHub Releases API bezogen und
mit `gdebi` installiert, um Abhängigkeiten automatisch aufzulösen.

---

## Lokale Nutzung

### Container interaktiv starten

```sh
./start.sh [--remote|-r] [quellverzeichnis] [shell] [homeverzeichnis] [ubuntu-version]
```

| Argument / Option | Beschreibung | Standard |
| --- | --- | --- |
| `--remote`, `-r` | Remote-Image von der GHCR verwenden (`ghcr.io/linuxmuster/lmndev-runner`) statt des lokal gebauten Images. Ist das Image noch nicht lokal vorhanden, wird es automatisch per `docker pull` bezogen. | lokales Image |
| `quellverzeichnis` | Wird als `/workspace/build` eingebunden | aktuelles Verzeichnis |
| `shell` | Shell im Container: `bash`, `zsh`, `ash`, `fish` | `DEFAULT_SHELL` aus `config` |
| `homeverzeichnis` | Host-Verzeichnis für `/home/build` | keines |
| `ubuntu-version` | Zu verwendendes Image-Tag: `24.04`, `26.04`, `latest` | `UBUNTU_TAG`-Env-Variable oder `latest` |

Die Shell kann auch über die Umgebungsvariable `DEFAULT_SHELL` gesetzt werden.
Das Home-Verzeichnis kann alternativ über `BUILD_HOME` übergeben werden.
Die Ubuntu-Version kann alternativ über die Umgebungsvariable `UBUNTU_TAG` gesetzt werden.

**Beispiele:**

```sh
# Einfacher Start mit Standard-Shell und lokalem Image
cd ~/src/linuxmuster-base7
/pfad/zu/lmndev-runner/start.sh .

# Remote-Image von GHCR statt lokalem Image verwenden
/pfad/zu/lmndev-runner/start.sh --remote ~/src/linuxmuster-base7

# Remote-Image, bestimmte Ubuntu-Version
/pfad/zu/lmndev-runner/start.sh -r ~/src/linuxmuster-base7 bash "" 24.04
UBUNTU_TAG=24.04 /pfad/zu/lmndev-runner/start.sh --remote ~/src/linuxmuster-base7

# Ubuntu 24.04 lokales Image verwenden
/pfad/zu/lmndev-runner/start.sh ~/src/linuxmuster-base7 bash "" 24.04

# Ubuntu-Version per Umgebungsvariable
UBUNTU_TAG=24.04 /pfad/zu/lmndev-runner/start.sh ~/src/linuxmuster-base7

# Mit eigenem Home-Verzeichnis und bestimmter Ubuntu-Version
/pfad/zu/lmndev-runner/start.sh ~/src/linuxmuster-base7 zsh ~/lmndev-home 24.04

# Home-Verzeichnis per Umgebungsvariable
BUILD_HOME=~/lmndev-home /pfad/zu/lmndev-runner/start.sh ~/src/linuxmuster-base7
```

`ghcr-start.sh` ist ein Kompatibilitäts-Wrapper, der intern `./start.sh --remote "$@"` aufruft.

```sh
# Im Container:
linuxmuster-base7.sh
```

### Paket in einem einzigen Befehl bauen

Hinweis: Falls im Wurzelverzeichnis der Paketquelle ein ausführbares Skript `buildpackage.sh`
liegt, wird dieses zum Paketbau verwendet. 

```sh
# Standard-Image (latest) verwenden — Pakete landen im Host-Verzeichnis ./output/
mkdir -p output
docker run --rm \
  -v "$PWD:/workspace/build" \
  -v "$PWD/output:/workspace/output" \
  lmndev-runner:latest \
  /opt/lmndev/build/linuxmuster-base7.sh

# Ubuntu 24.04 Image explizit verwenden
mkdir -p output
docker run --rm \
  -v "$PWD:/workspace/build" \
  -v "$PWD/output:/workspace/output" \
  lmndev-runner:24.04 \
  /opt/lmndev/build/linuxmuster-base7.sh
```

### Ausgabeverzeichnis festlegen

Die erzeugten `.deb`-Dateien werden standardmäßig nach `/workspace/output` im
Container geschrieben. Ein Host-Verzeichnis dort einbinden, um die Pakete nach dem
Lauf zu erhalten:

```sh
mkdir -p "$HOME/packages"
docker run --rm \
  -v "$PWD:/workspace/build" \
  -v "$HOME/packages:/workspace/output" \
  lmndev-runner:latest \
  /opt/lmndev/build/linuxmuster-base7.sh
```

Soll ein völlig anderer Pfad verwendet werden, `OUTPUT_DIR` explizit überschreiben:

```sh
docker run --rm \
  -v "$PWD:/workspace/build" \
  -v "$HOME/packages:/output" \
  -e OUTPUT_DIR=/output \
  lmndev-runner:latest \
  /opt/lmndev/build/linuxmuster-base7.sh
```

---

## Nutzung als GitHub Actions Runner

Das Image kann in jedem GitHub Actions Workflow als Job-Container eingesetzt werden.
Alle Build-Abhängigkeiten der unterstützten Projekte sind bereits im Image enthalten.

Die Images sind mit versionsspezifischen Tags verfügbar:

| Tag | Ubuntu-Version | Verwendung |
| --- | --- | --- |
| `:latest` | 26.04 (primär) | `lmn74` und neuere Distributionen |
| `:26.04` | 26.04 | `lmn74` und neuere Distributionen |
| `:24.04` | 24.04 | `lmn73` und ältere Distributionen |

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/linuxmuster/lmndev-runner:latest

    steps:
      - uses: actions/checkout@v7
        with:
          path: build
      - run: /opt/lmndev/build/linuxmuster-base7.sh
        env:
          OUTPUT_DIR: ${{ github.workspace }}/output
```

Die Buildskripte befinden sich im Container unter `/opt/lmndev/build/` und sind
über `$PATH` direkt aufrufbar.

---

## Release-Workflows

Für jedes unterstützte Projekt liegt im Verzeichnis `workflows/` eine fertige
Beispieldatei `PROJEKT.release.yml`. Diese kann direkt in das jeweilige
Projekt-Repository kopiert und als GitHub Actions Release-Workflow verwendet werden.

### Verwendung

1. Die passende Datei aus `workflows/` in das Projekt-Repository kopieren:

   ```sh
   cp workflows/linuxmuster-base7.release.yml \
      ~/src/linuxmuster-base7/.github/workflows/release.yml
   ```

2. Im Projekt-Repository drei Secrets hinterlegen
   (`Settings → Secrets and variables → Actions`):

   | Secret | Beschreibung |
   | --- | --- |
   | `REPO_HOST` | Hostname des APT-Repository-Servers |
   | `REPO_USER` | SSH-Benutzername auf dem Server |
   | `REPO_SSH_KEY` | Privater SSH-Schlüssel (ohne Passphrase) |

3. Einen Release-Tag setzen — der Workflow startet automatisch:

   ```sh
   git tag v7.3.5-0
   git push origin v7.3.5-0
   ```

### Ablauf des Release-Workflows

Der Workflow besteht aus vier sequenziellen Jobs:

```text
resolve ──→ build ──→ release ──→ publish
```

| Job | Beschreibung |
| --- | --- |
| **resolve** | Liest die Ziel-Distribution aus `debian/changelog` und wählt das passende Runner-Image: `lmn74` und höher → `:latest` (Ubuntu 26.04), alle anderen → `:24.04`. |
| **build** | Baut das Paket im von `resolve` gewählten `lmndev-runner`-Container. Version und Distribution werden automatisch aus der ersten Zeile von `debian/changelog` gelesen (z. B. `linuxmuster-base7 (7.3.5-0) lmn73; urgency=medium`). |
| **release** | Erstellt einen GitHub Release mit den erzeugten `.deb`-Dateien. |
| **publish** | Überträgt die Pakete per SSH auf den APT-Repository-Server und aktualisiert den Repository-Index (`repo-update lmn73` bzw. `repo-update lmn74`). |

Die Ziel-Distribution (`lmn73` oder `lmn74`) und das Runner-Image werden dabei
**automatisch** aus `debian/changelog` ermittelt — es ist keine manuelle Auswahl nötig.

### Tag-Format

Der Workflow reagiert auf Tags, die dem Muster `v[0-9]*` entsprechen, also z. B.:

```text
v7.3.5-0
v7.4.0-1
```

### Optional: Shell-Test-Harness

Projekte, die eine `tests/shell/`-Harness mitbringen (POSIX-`sh`-/Busybox-`ash`-
Tests; siehe `tests/shell/README.md` von linuxmuster-linbo7 als
Referenzimplementierung), können zusätzlich `workflows/shell-tests.yml`
kopieren:

```sh
cp workflows/shell-tests.yml \
   ~/src/linuxmuster-linbo7/.github/workflows/shell-tests.yml
```

Der Workflow führt `tests/shell/run.sh` unter beiden Shells im
`lmndev-runner`-Container aus und benötigt keine Secrets. Für sich genommen
ist er nur informativ; um ihn zu einem echten Release-Gate zu machen, einen
`test`-Job ergänzen, der ihn aufruft, und ihn in den `needs:` des `build`-Jobs
aufnehmen — siehe `release.yml` von linuxmuster-linbo7 für die Verdrahtung.

---

## Pro-Projekt-Buildskripte

Jedes Projekt hat ein eigenes Buildskript unter `build/PROJEKT.sh`. Im Container sind
diese unter `/opt/lmndev/build/` installiert und direkt per Name aufrufbar.

Alle Skripte verwenden die gemeinsame Funktion `build_package()` aus `build/common.sh`.

### Umgebungsvariablen

| Variable | Beschreibung | Standard |
| --- | --- | --- |
| `WORKSPACE` | Quellverzeichnis | `$GITHUB_WORKSPACE` oder aktuelles Verzeichnis |
| `OUTPUT_DIR` | Zielverzeichnis für `.deb`-Dateien | `/workspace/output` |
| `BUILD_FLAGS` | Zusätzliche `dpkg-buildpackage`-Flags | *(leer)* |
| `CCACHE_DIR` | ccache-Verzeichnis | `/tmp/ccache` |

`ccache` wird automatisch aktiviert, wenn es im Container verfügbar ist.

### Sonderfall `linuxmuster-linbo7`

Der Linbo-Build ist sehr ressourcenintensiv (Kernel, Netzwerktreiber, Busybox). Das
Skript `build/linuxmuster-linbo7.sh` setzt automatisch:

```sh
MAKEFLAGS="-j$(nproc)"
DEB_BUILD_OPTIONS="parallel=$(nproc)"
```

#### Vorgebaute Kernel (linbo 4.3)

Branches mit `build/bin/kernel-sync.sh` (linbo 4.3) kompilieren die Kernel nicht bei
jedem Paketbau. Kernel und Module liegen in `kernel/` und werden mit dem
historienlosen Branch `kernels-<major.minor>` abgeglichen (siehe linuxmuster-linbo7
Issue #186):

- Der Job `build` aus `workflows/linuxmuster-linbo7.release.yml` holt vor dem Bau die
  vorgebauten Kernel; kompiliert wird nur, wenn einer fehlt.
- Ein manueller Lauf mit dem Input `kernels` führt nur den Job `kernels` aus. Er baut
  neuere kernel.org-Versionen und pusht sie nach `kernels-<major.minor>`. Lokal
  anstoßen mit `build/bin/kernel-sync.sh build -w`; das wartet und holt das Ergebnis.
- Ein manueller Lauf mit abgeschaltetem Input `publish` baut nur das Paket, ohne
  GitHub-Release und ohne Update von `linuxmuster/deb`.
- Bei lokalen Builds lässt `BUILDKERNELS=yes` in der Container-Umgebung
  (`docker run -e BUILDKERNELS=yes ...`) den Bau neuere kernel.org-Versionen
  kompilieren.

Branches ohne `kernel-sync.sh` (7.4, Kernel aus Ubuntu) überspringen das Holen; der
Job `kernels` bricht dort mit einem Hinweis ab.

---

## Image veröffentlichen (GHCR)

Das enthaltene Workflow `.github/workflows/build-push.yml` baut bei jedem Push auf
`main` automatisch alle Images und pusht sie zu GHCR:

```text
ghcr.io/linuxmuster/lmndev-runner:24.04
ghcr.io/linuxmuster/lmndev-runner:26.04
ghcr.io/linuxmuster/lmndev-runner:latest   ← Alias für die primäre Version (26.04)
```

### Voraussetzungen im lmndev-runner-Repository

Im Repository unter `Settings → Actions → General` muss gesetzt sein:

> **Workflow permissions:** Read and write permissions

Damit kann der Workflow das Image in die GitHub Container Registry schreiben.

### Manueller Build und Push

```sh
# Alle Versionen lokal bauen
./build.sh all

# Manuell pushen (nach gh auth login oder docker login ghcr.io)
docker push ghcr.io/linuxmuster/lmndev-runner:24.04
docker push ghcr.io/linuxmuster/lmndev-runner:26.04
docker push ghcr.io/linuxmuster/lmndev-runner:latest
```

---

## Lizenz

Dieses Projekt ist Teil der [linuxmuster.net](https://linuxmuster.net) Entwicklungsumgebung.