Troubleshooting Guide

Collective Context (CC) Knowledge Base Entry

Session-Kontext

• Datum: 2025-09-09
• Teilnehmer: User (SysOps), Claude
• System: Mail-in-a-Box v73 auf Ubuntu 22.04
• Problem: Nextcloud-Update-Fehler nach Mail-in-a-Box Upgrade
• Lösung: Neuinstallation statt manuelle Reparatur

Executive Summary

Mail-in-a-Box's Architektur-Philosophie: Alle Daten in /home/user-data/ für einfache Backup/Restore. Bei Nextcloud-Problemen nicht manuell reparieren, sondern Backup → Deinstallation → Neuinstallation durch Mail-in-a-Box.

Das Problem

Initiale Fehlermeldung

Installing Nextcloud (contacts/calendar)...
Upgrading Nextcloud --- backing up existing installation...
Upgrades from Mail-in-a-Box prior to v60 with Nextcloud 19 or earlier are not supported.
Setup will continue, but skip the Nextcloud migration.

Root Cause Analyse

1. Versionskonflikte: Config zeigte Version 15.0.8.1, Software war 25.0.7
2. Multiple Config-Dateien:
   • /home/user-data/owncloud/config.php (primär)
   • /usr/local/lib/owncloud/config/config.php (sekundär)
3. Bug im Mail-in-a-Box Script: Regex ^1[3456789] matched fälschlicherweise auf Version 27

Kernerkenntnisse

Mail-in-a-Box Architektur-Prinzip

"Extrem wartungsfreundlich" bedeutet:

• ALLE persistenten Daten und Configs in /home/user-data/
• Komplette Systemwiederherstellung:
  1. Backup von /home/user-data/
  2. Neue Ubuntu-Box
  3. bash <(curl -s https://mailinabox.email/bootstrap.sh)
• System rebuildet sich selbst aus den Daten

Verzeichnisstruktur

/home/user-data/                    # Root für alle Benutzerdaten
├── owncloud/                       # Nextcloud-Datenverzeichnis
│   ├── config.php                  # PRIMÄRE Config (Mail-in-a-Box liest diese!)
│   ├── owncloud.db                 # SQLite Datenbank
│   └── [user-folders]/             # Benutzerdaten
│
/usr/local/lib/owncloud/            # Nextcloud-Installation
├── config/
│   └── config.php                  # Sekundäre Config (Link oder Kopie)
├── apps/                           # Nextcloud Apps
└── core/                           # Nextcloud Core

Fehlgeschlagene Lösungsversuche

❌ Versuch 1: Manuelles schrittweises Update

# Update-Kette: 25 → 26 → 27 → 28 → 29
sudo -u www-data php /usr/local/lib/owncloud/occ upgrade

Problem: Version-Inkonsistenzen zwischen verschiedenen Config-Dateien

❌ Versuch 2: Config-Synchronisation

# Versuch, Configs zu harmonisieren
sed -i "s/'version' => '[^']*'/'version' => '26.0.13.1'/" config.php

Problem: Mail-in-a-Box prüft mehrere Stellen, manuelle Fixes brechen

❌ Versuch 3: Nur Version-String anpassen

Problem: Datenbank-Schema passte nicht zur Software-Version

Die funktionierende Lösung

✅ Saubere Neuinstallation

# 1. Backup sichern
sudo mv /home/user-data/owncloud /home/user-data/owncloud-backup

# 2. Nextcloud-Installation komplett entfernen
sudo rm -rf /usr/local/lib/owncloud

# 3. Leeres Datenverzeichnis erstellen
sudo mkdir -p /home/user-data/owncloud
sudo chown www-data:www-data /home/user-data/owncloud

# 4. Mail-in-a-Box macht den Rest
bash <(curl -s https://mailinabox.email/bootstrap.sh)

Ergebnis:

• Nextcloud 26.0.13 sauber installiert
• Keine Fehlermeldungen mehr
• System vollständig funktionsfähig

Debugging-Kommandos

Version-Checks

# Nextcloud Software-Version
sudo -u www-data php /usr/local/lib/owncloud/occ -V

# Config-Versionen prüfen
grep version /home/user-data/owncloud/config.php
grep version /usr/local/lib/owncloud/config/config.php

# Nextcloud Status
sudo -u www-data php /usr/local/lib/owncloud/occ status

# Mail-in-a-Box Konfiguration
cat /etc/mailinabox.conf

Backup-Struktur verstehen

ls -la /home/user-data/owncloud-backup/
# Format: YYYY-MM-DD-HH:MM:SS/
#   ├── config.php         # Config zum Backup-Zeitpunkt
#   ├── owncloud.db       # Datenbank-Backup
#   └── owncloud-install/ # Software-Backup

Best Practices

Goldene Regeln für Mail-in-a-Box

1. Niemals gegen das System arbeiten
   • Mail-in-a-Box will die Kontrolle
   • Manuelle Eingriffe minimal halten
2. Bei Problemen: Neuinstallation > Reparatur
   • Backup der Daten
   • Komponente entfernen
   • Mail-in-a-Box neu machen lassen
3. Config-Management
   • Primäre Config: /home/user-data/owncloud/config.php
   • Änderungen nur dort, Rest sind Kopien/Links

Nach jeder Änderung

bash <(curl -s https://mailinabox.email/bootstrap.sh)

Typische Fehlerquellen

Lessons Learned

Technisch

1. Mail-in-a-Box's Version-Check hat einen Regex-Bug
2. Config in /home/user-data/ hat immer Priorität
3. Nextcloud-Updates über mehrere Major-Versionen sind problematisch
4. Mail-in-a-Box v73 installiert standardmäßig Nextcloud 26

Konzeptionell

1. Verstehe die Philosophie des Systems
   • Mail-in-a-Box = Wartungsfreundlichkeit durch Konvention
   • Nicht dagegen arbeiten, sondern damit
2. Dokumentation ist Gold wert
   • Fehler und Lösungswege dokumentieren
   • Nächster User/KI profitiert davon
3. Collective Context funktioniert
   • Gemeinsames Lernen statt isolierte Sessions
   • Wissen persistieren für die Community

Collective Context Metadata

Projekt-Information

• Repository: https://github.com/collective-context
• Community: recode@ (https://recode.at)
• Whitepaper: https://recode.at/collective-context-cc-whitepaper/
• Lizenz: Open Source - Wissen zum Wohle aller

Tags

#mailinabox #nextcloud #ubuntu #troubleshooting #config-management #collective-context #groundhog-day-solved

Versionierung

• Version: 1.0
• Erstellt: 2025-09-09
• Status: Living Document

Beitragende

• User (SysOps): Problem-Owner, Testing, Validierung, CC-Vision
• Claude: Analyse, Lösungsvorschläge, Dokumentation

Referenzen

• Mail-in-a-Box Official
• Mail-in-a-Box GitHub
• Nextcloud Documentation
• recode@ Community

Das Collective Context (CC) Projekt

Groundhog Day, was ist das? 📽️ Wie im Film “Und täglich grüßt das Murmeltier” erlebt Bill Murray denselben Tag immer und immer wieder. Genau das passiert mit KI-Sessions: Jeder Tag beginnt bei null, nichts bleibt hängen, alles wiederholt sich.

recode@ /YOU ❤️DevOps

"Evolution geschieht nicht durch Konkurrenz, sondern durch Kooperation und Symbiose."
- Collective Context Whitepaper