# Installation aus dem Archiv — llamacppctl

Diese Anleitung beschreibt, wie du `llamacppctl` aus dem fertigen Archiv
`llamacppctl-installable.tar.gz` installierst. Für die vollständige Bedienung
siehe [`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md).

---

## 1. Voraussetzungen auf der Zielmaschine

- **Python ≥ 3.10** (`python3 --version`)
- **Docker** mit erreichbarem Daemon (`docker version`)
- **NVIDIA-GPU** + Treiber + **NVIDIA Container Toolkit** (für `--gpus`)
- Ein **GGUF-Modell** auf dem Host

> Für einen reinen Konfigurations-/Trockenlauf (`--print-effective-config`,
> `--dry-run`) reicht Python; Docker/GPU/Modell werden erst für echte
> `--start`/`--check`/`--chat`-Aufrufe gebraucht.

---

## 2. Integrität prüfen (optional, empfohlen)

```bash
gzip -t llamacppctl-installable.tar.gz && echo "Archiv OK"
tar tzf llamacppctl-installable.tar.gz | head        # Inhalt ansehen
```

Das Archiv enthält ausschließlich Quellcode, Tests, Doku, Manpage,
`llama.cpp.config.example` und `scripts/smoke.sh` — **keine** persönliche
`llama.cpp.config`, keine `.venv`, keine `.git`-Historie und keine Geheimnisse.

---

## 3. Entpacken und installieren

```bash
tar xzf llamacppctl-installable.tar.gz
cd llamacppctl

python3 -m venv .venv
source .venv/bin/activate
pip install .
```

Danach steht das Konsolen-Kommando `llamacppctl` zur Verfügung:

```bash
llamacppctl --help
```

> Zum Entwickeln stattdessen `pip install -e ".[dev]"` (editable + Tests).

---

## 4. Konfiguration anlegen

```bash
cp llama.cpp.config.example llama.cpp.config
# llama.cpp.config an den Host anpassen: hf_home (z. B. ${HF_HOME}),
# model_path, gpu_device, host_port, container_name …
```

Auflösung prüfen, ohne etwas zu starten:

```bash
llamacppctl --print-effective-config --config llama.cpp.config
```

Das zeigt die vollständig aufgelöste Konfiguration als JSON **und** das
`docker run`-Kommando, das `--start` ausführen würde.

---

## 5. Erststart

```bash
llamacppctl --start --config llama.cpp.config
llamacppctl --check --config llama.cpp.config
llamacppctl --chat  --config llama.cpp.config -p "Sag kurz Hallo."
```

Weitere Aktionen, Optionen und Fehlersuche: [`BEDIENUNGSANLEITUNG.md`](BEDIENUNGSANLEITUNG.md).

---

## 6. Tests (optional)

```bash
pip install -e ".[dev]"
python -m pytest -q
```

---

## 7. Archiv selbst neu bauen / verifizieren

Das Archiv wird reproduzierbar von `build_archive.py` erzeugt. Es

1. prüft, ob alle erforderlichen Projektdateien vorhanden sind,
2. gleicht die deklarierten Abhängigkeiten in einer frischen venv ab,
3. lässt die komplette Test-Suite laufen,
4. baut das `.tar.gz` (nur Allowlist: `src/ tests/ docs/ man/ scripts/` + `pyproject.toml`, `README.md`, `LICENSE`, `CHANGELOG.md`, `requirements*.txt`, `llama.cpp.config.example`, `build_archive.py`),
5. öffnet das Archiv erneut und verifiziert die enthaltenen Dateien,
6. installiert das Paket aus dem Archiv in einer weiteren frischen venv und testet das Konsolenskript.

```bash
python3 build_archive.py                       # -> ../llamacppctl-installable.tar.gz
python3 build_archive.py --output /pfad/x.tar.gz
python3 build_archive.py --skip-pip-check --skip-smoke-test   # ohne Netz-Schritte
```

Weil `build_archive.py` selbst im Archiv liegt, lässt sich das Archiv jederzeit
unabhängig neu bauen und verifizieren.