Sylius Admin: Konfiguration

Sylius Admin konfigurieren: Umgebungsvariablen, .env-Dateien für Stage und Prod, Admin-User mit ROLE_API_ACCESS, X-Stage-Api-Key, Bild-Upload-Verzeichnis und die Auswahl der .env durch SYLIUS_ENV_NAME.

English Version

Zurück zur Übersicht

Sylius Admin: Konfiguration

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Jede Server-Instanz bedient genau eine Sylius-Umgebung. Die Konfiguration kommt aus einer .env-Datei pro Umgebung, es gibt keine Einstellungen im Claude-Code-Manifest außer der Auswahl der Umgebung.

Umgebungsvariablen

Diese Variablen stehen in der .env-Datei der jeweiligen Umgebung. Kopiere immer die mitgelieferte .env.example als Vorlage, statt eine Datei von Grund auf neu zu schreiben (siehe Hinweis unten).

Variable	Erforderlich	Standard	Beschreibung
`SYLIUS_ENVIRONMENT`	Ja	-	`stage` oder `prod`. Jeder andere Wert verhindert den Start. Die Vorlage enthält `stage`.
`SYLIUS_BASE_URL`	Ja	-	Basis-URL des Shops. Ein abschließender Schrägstrich wird entfernt.
`SYLIUS_ADMIN_EMAIL`	Ja	-	E-Mail-Adresse des Admin-Users für die API.
`SYLIUS_ADMIN_PASSWORD`	Ja	-	Passwort dieses Users.
`SYLIUS_API_KEY`	Nein	leer	Zusätzliches Shared Secret, das als Header `X-Stage-Api-Key` bei jedem Request mitgeschickt wird, auch beim Login. Nur für Stage; auf Prod leer lassen.
`SYLIUS_IMAGE_UPLOAD_BASE_DIR`	Nein	leer	Absoluter, existierender Pfad. Nur Dateien innerhalb dieses Verzeichnisses darf `add_product_image` beziehungsweise `add_taxon_image` hochladen. Leer bedeutet: Datei-Upload ist deaktiviert (`cdn_url` funktioniert trotzdem).

Eine Variable, die in einer handgeschriebenen .env ganz fehlt (statt leer zu sein), erbt einen zufällig im Prozess gesetzten Wert. Deshalb immer von .env.example kopieren, die beide optionalen Schlüssel explizit leer enthält.

Auswahl der .env-Datei

run.py bestimmt beim Start, welche Datei geladen wird, in dieser Reihenfolge:

Variable (Prozess)	Wirkung
`SYLIUS_ENV_FILE`	Absoluter Pfad zu einer vorhandenen Datei. Gewinnt, wenn beide Variablen gesetzt sind. Ein relativer Pfad oder eine fehlende Datei bricht den Start ab.
`SYLIUS_ENV_NAME`	`stage` oder `prod`. Lädt `~/.claude-plugin-syliusadmin/<name>/.env`. Das Plugin setzt diese Variable für seine beiden Server in der `.mcp.json`. Ein anderer Wert oder eine fehlende Datei bricht den Start ab.
keine von beiden	Die `.env` direkt neben `run.py` (Verhalten der manuellen Installation).

Die Datei wird mit Vorrang geladen: Werte aus der Datei überschreiben bereits im Prozess gesetzte SYLIUS_*-Variablen.

Passen SYLIUS_ENV_NAME und SYLIUS_ENVIRONMENT in der Datei nicht zusammen, verweigert der Server den Start. Eine prod-Registrierung kann sich so nie als stage melden, während sie in Wirklichkeit gegen den Live-Shop schreibt.

Beispiel: Stage

# ~/.claude-plugin-syliusadmin/stage/.env
SYLIUS_ENVIRONMENT=stage
SYLIUS_BASE_URL=https://stage.example.com
SYLIUS_ADMIN_EMAIL=api@example.com
SYLIUS_ADMIN_PASSWORD=...
SYLIUS_API_KEY=...
SYLIUS_IMAGE_UPLOAD_BASE_DIR=/home/dein-user/shop-bilder

Beispiel: Prod

# ~/.claude-plugin-syliusadmin/prod/.env
SYLIUS_ENVIRONMENT=prod
SYLIUS_BASE_URL=https://shop.example.com
SYLIUS_ADMIN_EMAIL=api@example.com
SYLIUS_ADMIN_PASSWORD=...
SYLIUS_API_KEY=
SYLIUS_IMAGE_UPLOAD_BASE_DIR=

Sylius-Admin-User

Der Server meldet sich über POST /api/v2/admin/administrators/token mit E-Mail und Passwort an und bekommt ein JWT zurück. Dafür braucht er einen eigenen Admin-User.

php bin/console sylius:create-admin-user

Der User braucht zusätzlich die Rolle ROLE_API_ACCESS. ROLE_ADMINISTRATION_ACCESS (Zugriff auf das Admin-Panel) allein reicht für die Admin API nicht: Der Login klappt dann, jeder Tool-Aufruf scheitert aber mit HTTP 403. In der Community Edition gibt es dafür keine Oberfläche, die Rolle ergänzt du im Feld roles der Tabelle sylius_admin_user.

Granulare Admin-Rollen gibt es in Sylius nur in der kostenpflichtigen Plus-Edition. In der Community Edition ist jeder Admin-User technisch Voll-Admin. Die Beschränkung auf Katalog und Shop-Konfiguration kommt allein daher, dass der Server keine Bestell-, Kunden- oder Promotion-Tools hat und jeden Request gegen eine eigene Pfad-Allowlist prüft.

Den Standard-Demo-Admin solltest du auf produktiven Systemen entfernen und stattdessen einen eigenen API-User verwenden.

Stage: X-Stage-Api-Key

Ist die Stage-Instanz per Basic Auth geschützt, kollidiert diese mit dem JWT, weil beide den Authorization-Header brauchen. In dem Setup, für das der Server gebaut wurde, ist /api/v2/admin/ deshalb von Basic Auth ausgenommen und stattdessen mit einem geteilten Secret im Header X-Stage-Api-Key abgesichert. Trage dieses Secret in SYLIUS_API_KEY ein. Es muss exakt dem Wert entsprechen, den die Stage-Instanz erwartet.

Der Server schickt den Header bei jedem Request mit, sobald SYLIUS_API_KEY gesetzt ist, unabhängig von SYLIUS_ENVIRONMENT. Auf Prod lässt du die Variable leer.

Bild-Upload konfigurieren

SYLIUS_IMAGE_UPLOAD_BASE_DIR muss ein absoluter Pfad zu einem vorhandenen Verzeichnis sein. Relative Pfade im Tool-Aufruf werden gegen dieses Verzeichnis aufgelöst, alle Pfade müssen nach der Auflösung (inklusive Symlinks) darin liegen. Erlaubt sind .jpg, .jpeg, .png, .gif und .webp bis 10.000.000 Bytes.

Das Verzeichnis liegt auf dem Rechner, auf dem der MCP-Server läuft, nicht auf dem Shop-Server. Details und Grenzen stehen auf der Seite Sicherheit und Datenschutz.

Optionale Sylius-Plugins im Shop

Einige Tools sprechen Endpunkte von Sylius-Plugins an. Sie funktionieren nur, wenn das jeweilige Plugin im Shop installiert ist:

Plugin im Shop	Betroffene Funktion
`sylius-seo-suite-pro`	SEO-Felder `metaTitle`, `canonicalPathOverride`, `robotsIndex`, `robotsFollow` in den Übersetzungen von Produkten und Kategorien
`sylius-cdn-product-images`	Parameter `cdn_url` bei `add_product_image` und `add_taxon_image`
`sylius-marketplace-redirect`	Die fünf Marketplace-Link-Tools
`sylius-product-custom-inputs`	Die zwei Tools für Eingabefeld-Definitionen

Ohne das jeweilige Plugin antwortet Sylius mit einem Fehler (bei den SEO-Feldern wird der Schlüssel stillschweigend ignoriert, siehe Tools).