Mealie v0.5 auf v3 upgraden: kein direktes Upgrade, dafür drei Fallstricke

Mealie ist eine selbst gehostete Rezepte-App. Wer noch die alte hkotel/mealie-Version (v0.5.x) betreibt, wird früher oder später merken: Ein direktes docker pull + Restart zerschießt die Datenbank. Die neue Version (ghcr.io/mealie-recipes/mealie) hat ein komplett anderes Datenbankschema.

Der empfohlene Weg: Export aus der alten Instanz, neue Instanz parallel aufbauen, importieren, testen, Cutover.

Klingt simpel. Ist es meistens auch — bis zu den drei Stellen, die die Doku entweder wegläßt oder im Kleingedruckten vergräbt.

Das Setup

Alt: hkotel/mealie:v0.5.6, Port 8090, LDAP-Auth, läuft seit Jahren. Neu: ghcr.io/mealie-recipes/mealie:latest, Port 8093, Keycloak OIDC.

Vorgehen: Parallel starten mit Test-Domain (food-new.deathstar.lan), nach Bewährung Cutover auf die echte Domain (food.deathstar.lan).

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:latest
    container_name: mealie-new
    ports:
      - "8093:9000"
    volumes:
      - ./data:/app/data/
    environment:
      BASE_URL: "https://food-new.deathstar.lan"
      DB_ENGINE: sqlite
      OIDC_AUTH_ENABLED: "true"
      OIDC_CONFIGURATION_URL: "https://auth.deathstar.lan/realms/<REALM>/.well-known/openid-configuration"
      OIDC_CLIENT_ID: "mealie"
      OIDC_CLIENT_SECRET: "${OIDC_CLIENT_SECRET}"
      OIDC_AUTO_REDIRECT: "false"
      ALLOW_PASSWORD_LOGIN: "true"
    extra_hosts:
      - "auth.deathstar.lan:<IP-DES-KEYCLOAK-HOSTS>"

ALLOW_PASSWORD_LOGIN: "true" ist wichtig — sonst kommst du nach einem OIDC-Problem nicht mehr rein.

OIDC_AUTO_REDIRECT: "false" — macht den Keycloak-Button sichtbar statt sofort zu redirecten. Hilfreich für den lokalen Admin-Login als Fallback.

Fallstrick 1: Backup Restore ≠ Migration

Die alte v0.5.x Instanz hat einen Export-Endpunkt. Man bekommt eine ZIP-Datei mit recipes/, settings/, usw.

Wer diese ZIP in v3 unter Admin → Data Management → Backups → Restore hochlädt, bekommt:

Invalid backup file. file does not contain required elements (data directory and database.json)

Verständlich — v3 erwartet für Backup-Restore sein eigenes Format (mit data/ und database.json). Das v0.5.x Format ist was anderes.

Die richtige Stelle: Admin → Data Management → Migrations → Source: Mealie

Dort wird explizit das v0.5.x ZIP-Format unterstützt. Alle Rezepte landen sauber in der neuen Instanz.

Fallstrick 2: OIDC-User ohne Admin-Rechte

Beim ersten Login über Keycloak wird der User automatisch angelegt — mit der Standard-Rolle “User”. Das ist meistens was man will.

Was man sich dabei aber nicht erwartet: Auch der eigene Admin-Account aus Keycloak landet mit eingeschränkten Rechten. API-Tokens erstellen, User verwalten, Migrationen starten — alles gesperrt.

Fix:

1. Mit dem lokalen Mealie-Admin einloggen (Password-Login, nicht OIDC)
2. Admin → Users → [Username] → Advanced
3. Admin-Rechte aktivieren

Danach kann der OIDC-User alles. Aber man muss es manuell tun — es gibt keine Keycloak-Rolle, die automatisch Mealie-Admin macht.

Fallstrick 3: nginx sites-enabled vs. sites-available

Der Klassiker, der nie alt wird.

Setup: Der Reverse Proxy (srv-chewbacca.deathstar.lan) hat nginx. Die Config liegt in /etc/nginx/sites-enabled/food.conf — als eigene Datei, kein Symlink zu sites-available.

Nach dem Cutover wird die neue Config lokal bearbeitet und deployt:

scp food.conf root@srv-chewbacca:/etc/nginx/sites-available/food.conf
ssh srv-chewbacca 'nginx -t && systemctl reload nginx'

nginx meldet syntax ok, reload erfolgreich. Und trotzdem: Die alte Seite kommt noch. Kein Keycloak, alte Version.

Warum? sites-enabled und sites-available sind auf diesem Server unabhängige Verzeichnisse. Kein Symlink-Mechanismus. scp nach sites-available hat die falsche Datei aktualisiert. sites-enabled/food.conf war unverändert.

# Prüfen welche Datei nginx wirklich liest:
nginx -T | grep "# configuration file"
# ODER:
ls -la /etc/nginx/sites-enabled/

Fix:

scp food.conf root@srv-chewbacca:/etc/nginx/sites-enabled/food.conf
ssh srv-chewbacca 'nginx -t && systemctl reload nginx'

Immer prüfen ob sites-enabled Symlinks oder eigene Dateien enthält — und dementsprechend deployen.

Zusammenfassung

Mealie v3 macht vieles besser als v0.5.x — OIDC-Support, aktive Entwicklung, besseres UI. Der Migrationspfad ist solide, wenn man weiß wo die Tücken sind.