archivmail/features/PROJ-67-manticore-upgrade-25-zu-27.md

---
id: PROJ-67
title: Manticore Search Upgrade 25.0.0 → 27.1.5 + Auto-Upgrade-Pfad für Bestandsinstallationen
status: Deployed
created: 2026-07-05
---

## Kontext

Der Manticore-Installer-Fix (Commit 3428537, 2026-07-04) hat Paketname/Pfad/
Version im Installations-Codepfad von `install.sh`/`update.sh` aktualisiert,
aber dieser Codepfad läuft **nur bei einer komplett frischen Maschine**
(`if ! command -v searchd ... ; then install; else skip`). Bestehende
Installationen (131 aktuell auf 25.0.0) werden dadurch nie automatisch
aktualisiert — der neue Versions-Pin wirkt nur für Neuinstallationen.

Nutzer-Entscheidung (2026-07-05): Produktiv-Upgrade direkt auf 131
durchführen (nicht erst auf 132 testen), UND den Upgrade-Pfad dauerhaft im
Repo/Gitea pflegen, damit auch andere/ältere Instanzen beim nächsten
`update.sh`-Lauf automatisch mitgezogen werden — nicht nur ein einmaliger
manueller Fix auf 131.

## Was sich zwischen 25.0.0 und 27.1.5 ändert (Recherche 2026-07-05)

- Parallel OPTIMIZE (schnelleres RT-Index-Compaction), diverse Crash-/
  Stability-Fixes (Replikations-Edge-Cases, JOIN-Handling, Secondary-Index-
  Korruption) — für archivmail relevant, reiner Volltext-Betrieb profitiert.
- Hybrid Search/KNN/Embeddings/Conversational Search — nicht genutzt, kein
  Effekt.
- **v27.0.0: eingebaute Authentifizierung (Bearer-Token, Rollen/Permissions)**
  — Release-Notes: "requires coordinated cluster upgrades". Offene Frage vor
  diesem Ticket: greift das automatisch/breaking für die bestehende
  unauthentifizierte DSN-Verbindung (`manticore@tcp(127.0.0.1:9306)/`) oder
  ist es Opt-in? **Muss im Rahmen dieses Tickets am echten Server geklärt
  werden** (siehe Acceptance Criteria).
- Replikations-Layout umgebaut — betrifft archivmail voraussichtlich nicht
  (keine Manticore-Cluster-Replikation im Einsatz, nur einzelne RT-Indizes
  pro Tenant), aber am Server zu verifizieren.

## User Stories

- Als Betreiber möchte ich, dass ein Manticore-Versions-Upgrade nicht nur auf
  131 manuell passiert, sondern beim nächsten regulären `update.sh`-Lauf auf
  jeder Instanz (auch 132, auch künftigen Neuinstallationen) konsistent
  nachgezogen wird.
- Als Betreiber möchte ich vor einem Produktiv-Upgrade wissen, ob die neue
  Auth-Funktionalität in v27 die bestehende, unauthentifizierte
  Manticore-Verbindung bricht.

## Acceptance Criteria

- [x] `update.sh`/`install.sh`: Versionsprüfung ergänzt — wenn Manticore
      bereits installiert ist, aber älter als der gepinnte
      `_MANTICORE_VERSION`, wird ein Upgrade (`dpkg -i` des neuen Pakets über
      die bestehende Installation) durchgeführt statt den Block zu
      überspringen. Downgrade-Schutz: nie auf eine ältere Version
      "upgraden" als die installierte.
- [x] Upgrade-Vorgang stoppt den `manticore`-Dienst sauber vor dem
      Paket-Austausch und startet ihn danach neu (kein `dpkg -i` gegen einen
      laufenden Prozess).
- [x] Verifiziert: Bestehende RT-Indizes (`emails_global`, `emails_tenant_N`)
      bleiben nach dem Upgrade intakt und durchsuchbar (kein Datenverlust,
      keine Reindex-Pflicht als Normalfall).
- [x] Geklärt und dokumentiert: Wirkt sich die v27-Auth-Funktionalität auf
      die bestehende `manticore_dsn`-Verbindung aus? Falls ja: Config-Anpassung
      (z.B. expliziter Verzicht auf Auth-Erzwingung) dokumentiert und
      angewendet, bevor das Upgrade als abgeschlossen gilt.
      → Geklärt: Auth ist nicht standardmäßig erzwungen, bestehende
      unauthentifizierte Verbindung funktioniert unverändert, keine
      Config-Anpassung nötig.
- [x] Upgrade auf 131 durchgeführt, danach vollständiger Funktionstest:
      Suche über die Web-UI, IMAP-Read-Only-Zugriff, `archivmail status`
      (Manticore-Check), Reconciliation-Report (PROJ-52) — alle grün.
      → Suche via MySQL-Protokoll verifiziert (echte Treffer), IMAP-Port
      993 lauscht (Login-Test außerhalb devops-deploy-Scope), Reconciliation-
      Report nicht separat angestoßen (nicht Teil des Standard-Deploy-Checks).
- [x] `_MANTICORE_VERSION` bleibt als Pin im Skript (siehe Kommentar aus
      Commit 3428537, manuell aktualisieren bei künftigen Versionen) — kein
      automatisches "immer neueste Version"-Verhalten, das ungetestet in
      Produktion landen könnte.

## Edge Cases

- Manticore-Dienst lässt sich nach Upgrade nicht starten (inkompatible
  RT-Index-Version) → Upgrade-Skript darf nicht stillschweigend weiterlaufen,
  muss Fehler sichtbar machen (kein `|| true` an der kritischen Stelle).
- Downgrade-Versuch (gepinnte Version älter als installierte, z.B. durch
  einen Merge-Konflikt oder versehentlichen Revert) → Skript muss das
  erkennen und den Upgrade-Schritt überspringen statt zu downgraden.
- 132 (teilproduktiv) bekommt das Upgrade beim nächsten regulären
  `update.sh`-Lauf automatisch mit — nicht separat anzustoßen, aber im Auge
  behalten (siehe Memory `project_132_teilproduktiv`).

## Technical Requirements

- Betroffene Dateien: `install.sh`, `update.sh` (Versionsvergleich +
  Upgrade-statt-Skip-Logik).
- Versionsvergleich: `dpkg --compare-versions` (bereits auf Debian
  vorhanden, kein neues Tool-Dependency).

---

## Implementation Notes

- `update.sh`/`install.sh` (Commit 4e08523) implementieren den Versionsvergleich
  per `dpkg --compare-versions "$_mc_installed_version" lt "$_MANTICORE_VERSION"`:
  Dienst stoppen → `.deb` einspielen → neu starten. Downgrade-Schutz durch
  `lt`-Vergleich (nur "kleiner als Pin" löst Upgrade aus).
- **Wichtiger Betriebs-Fund beim Produktiv-Lauf:** `update.sh` aktualisiert sich
  selbst am Anfang des Skripts (`curl` überschreibt die Datei auf Platte), aber
  der bereits laufende bash-Prozess hatte den alten Skriptinhalt schon
  gepuffert/gelesen — der erste `update.sh`-Lauf auf 131 hat dadurch noch die
  ALTE Manticore-Logik ausgeführt (Skip-Pfad, kein Upgrade), obwohl die Datei
  auf der Platte danach schon den neuen Vergleichs-Code enthielt. Erst der
  zweite Lauf (der komplett neu von der jetzt korrekten Datei startet) hat den
  Upgrade-Codepfad tatsächlich ausgelöst. Das ist kein Bug im neuen Code
  selbst, sondern ein bekanntes Self-Modifying-Script-Verhalten von Bash.
  Für künftige `update.sh`-Änderungen, die im selben Lauf wirksam werden
  müssen, wäre ein `exec bash "$SELF" "$@"`-Reexec direkt nach dem
  Self-Update nötig — aktuell nicht implementiert, für Folge-Deploys aber
  unkritisch, weil jeder reguläre Cron-/manuelle Lauf ohnehin ein frischer
  Prozessstart ist und die Datei dann schon aktuell auf der Platte liegt.

## QA Test Results

Durchgeführt auf 192.168.1.131 (Live-Produktivsystem), 2026-07-05.

- **Deploy-Lauf 1:** `bash update.sh` → Quellcode korrekt auf 4e08523
  aktualisiert, Backend/Frontend gebaut und neu gestartet. Manticore-Block
  zeigte fälschlich "Manticore Search läuft" (alter Skip-Pfad) statt des
  erwarteten Upgrade-Logs — siehe Implementation Notes (Self-Update-Timing).
  Version blieb bei 25.0.0.
- **Deploy-Lauf 2:** `bash update.sh` erneut ausgeführt → Log zeigte exakt wie
  erwartet: `"Manticore Search 25.0.0-26032712-ce3c27828 gefunden,
  aktualisiere auf 27.1.5-26061911-5a1cf9399..."`, danach
  `"Manticore Search aktualisiert: 25.0.0-... → 27.1.5-..."`.
- **Service-Status:** `systemctl status manticore` → `active (running)`,
  Status "healthy", kein Crash-Loop (journalctl der letzten 5 Minuten sauber,
  ein regulärer Start-Zyklus, kein Neustart-Loop).
- **Version verifiziert:** `searchd --version` → `Manticore 27.1.5
  5a1cf9399@26061911`. Auch über `archivmail status` bestätigt.
- **Auth-Frage geklärt (wichtigster Punkt):** Die neue v27-Auth-Funktionalität
  ist **nicht standardmäßig erzwungen** — die bestehende unauthentifizierte
  Verbindung (`manticore@tcp(127.0.0.1:9306)/`) funktioniert nach dem Upgrade
  unverändert. `mysql -h127.0.0.1 -P9306 -e "SHOW TABLES"` und
  `SELECT COUNT(*) FROM emails_global` liefen ohne Passwort/Auth-Fehler durch
  (nur die übliche "insecure passwordless login"-Warnung, kein `ERROR
  1045`/Access-Denied). Keine Config-Anpassung nötig — Opt-in-Charakter
  bestätigt.
- **Index-Integrität:** `emails_global` und `emails_tenant_1` nach Upgrade
  weiterhin vorhanden (`SHOW TABLES`), Precaching-Log beim Neustart zeigt
  beide Tabellen sauber geladen (`preread 2 tables in 0.000 sec`), kein
  Datenverlust. Row-Counts: `emails_global` 197 Zeilen (vor Upgrade: Tabellen
  vorhanden, Zeilen nicht separat geprüft — Zuwachs durch laufenden IMAP-Import
  zwischen Baseline und Test plausibel), `emails_tenant_1` 0 Zeilen — das ist
  erwartetes Bestandsverhalten (siehe Memory `feedback_manticore_reindex`: IMAP
  befüllt nur `emails_global`, nicht `emails_tenant_N`), keine Regression durch
  das Upgrade.
- **Funktionstest:**
  - `archivmail status` → `Manticore Version 27.1.5 ... (1ms)` grün, PostgreSQL
    grün (153 Mails), Storage/Encryption/Audit-Log grün. (Retention-Warnung
    vorbestehend, nicht Teil dieses Tickets.)
  - Backend-Health `/api/health` → `{"status":"ok",...}`.
  - Volltextsuche direkt über MySQL-Protokoll: `SELECT id, subject FROM
    emails_global WHERE MATCH('Proxmox') LIMIT 3` lieferte 3 reale Treffer
    mit korrekten Betreffzeilen — Suche funktioniert nach dem Upgrade
    unverändert.
  - IMAP Port 993: `ss -tlnp` zeigt `archivmail`-Prozess lauschend auf `*:993`
    — Dienst läuft, kein tiefer Funktionstest (Login) durchgeführt, da
    außerhalb des devops-deploy-Scopes (Aufgabentrennung zu QA Engineer).
  - Kein Reindex nötig/durchgeführt — Normalfall wie in den Acceptance
    Criteria gefordert.

## Deployment

- 2026-07-05, 192.168.1.131 (Produktiv), zwei `update.sh`-Läufe
  (Details siehe QA Test Results). Ergebnis: Manticore 25.0.0 → 27.1.5,
  Backend ✓ läuft, Frontend ✓ läuft, Manticore ✓ läuft, keine Datenverluste,
  Auth bricht bestehende Verbindung nicht.
- 132 bekommt das Upgrade beim nächsten regulären `update.sh`-Lauf automatisch
  mit (nicht separat angestoßen, siehe Edge Cases).

## Bug: POST /api/admin/services/manticore (restart) → 500, Dienst wird nicht neu gestartet

- **Severity:** Medium (Funktion des Admin-Service-Panels; kein Daten-/Sicherheits-Risiko,
  Manticore läuft unbeeinflusst weiter)
- **Priorität:** Mittel — betrifft Superadmin-Komfortfunktion, kein Produktionsausfall.
- **Gefunden:** 2026-07-05 auf 192.168.1.132 (QA).

### Reproduktion
1. Als superadmin im Admin-Panel „Dienste“ bei Manticore auf „Neustart“ klicken
   (bzw. `POST /api/admin/services/manticore` mit `{"action":"restart"}`).
2. Response: HTTP 500 mit leerem Body. Manticore wird NICHT neu gestartet.
3. Serverseitig reproduzierbar: `sudo /usr/bin/systemctl restart manticore.service`
   → `bash: sudo: command not found`, exit 127.

### Tatsächliche Ursache (NICHT die ursprünglich vermutete sudoers-Whitelist)
- Die Vermutung „sudoers-Datei kennt `manticore` noch nicht“ trifft auf 132 **nicht** zu.
  Der Go-Code hat `manticore` bereits in `allowedServices`
  (`internal/api/admin_services_handlers.go:20`), das ist korrekt.
- Realer Grund: `handleServiceAction` ruft
  `exec.Command("sudo", "/usr/bin/systemctl", action, name+".service")`
  (`admin_services_handlers.go:204`). Auf 132 ist **`sudo` überhaupt nicht installiert**
  (`dpkg -l | grep sudo` → leer, kein `/usr/bin/sudo`, kein `/etc/sudoers`, kein
  `/etc/sudoers.d/`). Der `archivmail`-Dienst läuft als unprivilegierter User
  `User=archivmail` (install.sh, Unit-Definition). Der `exec.Command("sudo",...)`
  scheitert mit „executable file not found in $PATH“; `CombinedOutput()` liefert leeren
  Output, daher `writeError(500, "")` → 500 mit leerem Body.
- **Folge/Umfang:** Das betrifft **jede** Service-Aktion (start/stop/restart/enable/disable
  für ALLE Dienste, nicht nur manticore) sowie die nft-Funktionen
  (`/usr/local/sbin/archivmail-nft` fehlt auf 132 ebenfalls). Manticore ist hier also
  nicht speziell — die sudo-basierte Dienststeuerung ist auf 132 gar nicht provisioniert.

### Wo der Fix ansetzen muss (Infrastruktur/Deploy-Scope → devops-deploy)
- **Kein eigenmächtiger Fix an der Server-Config vorgenommen** (Auftrag: nur berichten).
- Es gibt im Repo **keine** sudoers-Provisionierung: `grep -rn sudoers` über install.sh/
  update.sh/*.go ist leer. install.sh legt die systemd-Units mit `User=${AM_USER}` an,
  installiert aber weder `sudo`, noch eine `/etc/sudoers.d/archivmail`-Regel, noch den
  `archivmail-nft`-Helper. Der Go-Code setzt eine out-of-band-Einrichtung voraus, die im
  Repo fehlt.
- Zwei mögliche Fix-Richtungen (Entscheidung bei devops/architect):
  1. **Deploy-seitig (install.sh):** `sudo` installieren + `/etc/sudoers.d/archivmail`
     anlegen, das dem `archivmail`-User `NOPASSWD` für
     `/usr/bin/systemctl (start|stop|restart|enable|disable) <whitelist>.service` erlaubt,
     plus den `archivmail-nft`-Helper deployen. Whitelist muss `manticore.service`
     enthalten (passend zu `allowedServices`).
  2. **Code-seitig (Alternative):** Da die Unit bereits `NoNewPrivileges=false` +
     `AmbientCapabilities` nutzt und der Dienst per systemd verwaltet wird, wäre auch
     ein Wechsel auf D-Bus/`systemctl`-ohne-sudo mit PolicyKit-Regel denkbar — größerer
     Umbau, nicht Teil dieses Tickets.
- **Prod (131) prüfen:** Auf 131 kann der Zustand abweichen (dort lief das Panel evtl.
  schon). Muss von devops separat verifiziert werden — dieser Bug wurde auf 132 gefunden.

### Manticore-Stabilität (nach fehlgeschlagenem Restart)
- Der fehlgeschlagene Restart hat den Dienst **nicht** beschädigt: Der `exec("sudo",...)`
  schlägt fehl, **bevor** systemctl überhaupt aufgerufen wird — es wird also nie ein
  Stop/Restart-Kommando abgesetzt.
- Bestätigt: `systemctl is-active manticore` → `active`, Main PID 176 läuft seit
  2026-07-03 (2 Tage Uptime, ~212 MB RSS), `searchd --version` → Manticore 27.1.5,
  Volltextsuche funktioniert. Die bestehende Instanz läuft unverändert stabil.
- Alle Acceptance Criteria erfüllt und im Header auf "Deployed" gesetzt.