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

id, title, status, created

id	title	status	created
PROJ-67	Manticore Search Upgrade 25.0.0 → 27.1.5 + Auto-Upgrade-Pfad für Bestandsinstallationen	Deployed	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

• 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.
• Upgrade-Vorgang stoppt den manticore-Dienst sauber vor dem Paket-Austausch und startet ihn danach neu (kein dpkg -i gegen einen laufenden Prozess).
• Verifiziert: Bestehende RT-Indizes (emails_global, emails_tenant_N) bleiben nach dem Upgrade intakt und durchsuchbar (kein Datenverlust, keine Reindex-Pflicht als Normalfall).
• 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.
• 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).
• _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.