aYOUne

Migration Guide

Wer eine ältere aYOUne-Instanz (vor 2026.30) auf 2026.50+ heben möchte, sollte gestuft vorgehen. Hier der Pfad — auf Self-Hosting und SaaS gleichermaßen anwendbar.

Pfad-Übersicht

< 2026.30  ──┐
             ├──→ 2026.30.x  (Stop 1)
2026.30+ ────┴──→ 2026.40.x  (Stop 2)
                  └──→ 2026.50+  (Ziel)

Direkter Sprung von < 2026.30 auf 2026.50+ ist nicht unterstützt — Schema-Migrations sind nicht alle aufwärts-kompatibel ausgelegt.

Stop 1: Auf 2026.30.x

ay self-host-update --to 2026.30.5 --backup-first

Hier passiert:

  • MongoDB-Schema-Migration: aYOUneCustomers.packages strukturell normalisiert
  • aYOUneRoles.rights werden auf 3-Teil-Format umgestellt (<modul>.<entity>.<verb>)
  • ayounestates werden erstmalig befüllt (vorher in JSON-Files)

Verify:

ay status
ay doctor
mongosh $MONGO_URL --eval "db.ayounestates.estimatedDocumentCount()"
# sollte > 100 sein

Stop 2: Auf 2026.40.x

ay self-host-update --to 2026.40.0 --backup-first

Hier passiert:

  • Mongoose 7 → 8 (Document.update() entfernt — siehe Breaking Changes)
  • WebPushSubscribers Schema-Drift fix (_customerID von String zu ObjectId)
  • Atlas-Search-Indexes für Hub-Module

Verify:

mongosh $MONGO_URL --eval "db.webpushsubscribers.findOne()._customerID instanceof ObjectId"
# sollte true sein

Falls dein Code Document.update() nutzt — JETZT umstellen (siehe Breaking Changes).

Ziel: 2026.50+

ay self-host-update --to 2026.50.5 --backup-first

Hier passiert:

  • Two-Phase-Boot in Core (siehe Core Changelog)
  • registerModuleStates _appName-Scope (siehe Breaking Changes)
  • 13 neue Atlas-Indexes für Marketplace-Module

Setze:

# alle Services
AYOUNE_RELEASE_NAME: "<service-name>"
AYOUNE_BOOT_WATCHDOG_MS: 60000   # default, ggf. erhöhen

Aktiviere Health-Probes für Helm-Charts:

helm upgrade api-crm tolinax/node \
  --set probes.enabled=true \
  --reuse-values

Cross-Cutting: Foundation-Deps

Egal welchen Sprung du machst — am Ende:

# In jedem Service
npm install @tolinax/ayoune-core@latest
npm install @tolinax/ayoune-models@latest
npm install @tolinax/ayoune-interfaces@latest
npm run build
git add package.json package-lock.json
git commit -m "chore: bump foundation to 2026.50.x"

Lockfile-Commit ist Pflicht — npm ci in Production Docker-Build hängt sonst auf alter Version.

Wenn was schief geht

Symptom Ursache Fix
Pod CrashLoop nach Upgrade Schema-Migration nicht durch ayoune-migration Container manuell laufen lassen
init_error: license License zu alt LICENSE_KEY rotieren
Fehlende States im UI _appName nicht gesetzt ConfigMap-Update + Pod-Restart
Slow Atlas-Search Index fehlt ay setup atlas-indexes --apply

Rollback-Strategie

Vor jedem Stop ein Backup:

mongodump --uri=$MONGO_URL --archive=backup-pre-$(date +%F).archive --gzip

Bei Fehler:

ay self-host-update rollback        # zurück zur letzten Version
mongorestore --archive=backup-pre-2026-04-25.archive --gzip --drop

SaaS-Migration

Auf SaaS (*.ayoune.app) brauchst du nichts zu tun — Tolinax updated die Plattform für dich. Du wirst per Mail (in der "Notifications"-Channel release.published) informiert.

Verbindungen