Zum Inhalt springen
KendorDocs

kendor.yaml-Referenz

Für Aufgabenautoren ·

Jeder Schlüssel, den kendor.yaml akzeptiert, von runtime und services über routing und databases bis sandbox, mit Typen, Standardwerten und den beim Speichern geprüften Regeln.

kendor.yaml liegt im Stammverzeichnis des Projekts einer Aufgabe und sagt der Sandbox, was sie ausführen soll: eine Sprache samt Version, optional weitere Sprachen und Datenbanken sowie einen oder mehrere Dienste mit ihren Install-, Dev- und Test-Befehlen. Nur version, runtime und services sind Pflicht. Kendor prüft beim Speichern die gesamte Datei, und eine Datei mit Fehlern wird nicht gespeichert.

Wo die Datei liegt und wann sie gilt

Die Datei heißt kendor.yaml und liegt im Workspace-Stamm. In einem hochgeladenen Zip oder importierten Repository akzeptiert Kendor auch die Schreibweise kendor.yml.

Öffne im Aufgaben-Editor Einstellungen und wähle Runtime konfigurieren…. Der Dialog Runtime-Konfiguration hat einen Tab Formular und einen Tab Rohes YAML; beim Speichern wird kendor.yaml geschrieben und die Vorschau neu gestartet. Wenn du die Datei stattdessen von Hand bearbeitest, erscheint ein Banner kendor.yaml geändert, denn die Sandbox läuft weiter mit der vorherigen Einrichtung, bis du Speichern & neu starten wählst.

Beim Speichern führt Kendor die unter Validierungsregeln aufgeführten Prüfungen aus und prüft außerdem, dass jede Sprach- und Datenbankversion eine ist, die Kendor anbietet. Jedes Problem wird mit seinem Pfad in der Datei gemeldet, zum Beispiel services.web.dev.port.

Die Kopie von kendor.yaml in einer laufenden Sandbox wird bei jedem Start der Sandbox aus der gespeicherten Konfiguration neu erzeugt, sie zeigt also immer, was die Sandbox gerade ausführt.

Tipp. Beginne die Datei mit # yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Editoren, die den YAML-Language-Server nutzen, bieten dann Autovervollständigung und Inline-Fehler für jeden Schlüssel auf dieser Seite.

Was Kandidaten ändern können

Ein Kandidat kann kendor.yaml in seinem eigenen Workspace bearbeiten. Aus seiner Kopie werden nur vier Schlüssel der obersten Ebene gelesen: install, services, preview und routing. Seine Änderungen gelten, wenn die Sandbox neu startet, und nur, wenn die zusammengeführte Datei die Validierung weiterhin besteht; andernfalls bleibt deine Konfiguration bestehen. runtime, toolchains, databases, sandbox und kendor stammen immer aus deiner Datei, ebenso die Test-Befehle: Jedes test, das ein Kandidat schreibt, wird verworfen, und deine test-Befehle bleiben bei den von dir definierten Diensten erhalten.

Ein vollständiges Beispiel

Eine Node.js-API und ein Vite-Frontend, mit PostgreSQL und Valkey, plus ein Python-Worker:

kendor.yaml
# yaml-language-server: $schema=https://kendor.dev/config-schema/v1
version: 1
runtime:
  type: node
  version: "22"
  packageManager: npm
toolchains:
  - type: python
    version: "3.12"
databases:
  - type: postgres
    version: "18"
    name: shop
    init: db/init
  - type: valkey
    version: "9"
services:
  api:
    workDir: api
    install:
      commands:
        - npm ci
    dev:
      command: node --watch src/server.js
      port: 3000
      env:
        vars:
          WEB_URL: routing.web.url
          CACHE_URL: databases.valkey.url
          LOG_LEVEL: lit:debug
    test:
      command: node --test
  web:
    workDir: web
    install:
      commands:
        - npm ci
    dev:
      command: npm run dev -- --port $PORT
      port: 5173
      env:
        vars:
          VITE_API_URL: routing.api.url
    publicEnvPrefix: VITE_
  worker:
    workDir: worker
    install:
      commands:
        - pip install --user -r requirements.txt
    dev:
      command: python worker.py
preview:
  service: web
routing:
  - path: /api
    service: api
  - path: /
    service: web
requests:
  - name: List products
    url: http://localhost:3000/api/products
  - name: Create a product
    method: POST
    url: http://localhost:3000/api/products
    headers:
      Content-Type: application/json
    body: '{"name": "Mug", "price": 12}'
kendor:
  gradeService: api

Schlüssel der obersten Ebene

Unbekannte Schlüssel werden überall in der Datei abgelehnt, außer innerhalb von kendor.

Schlüssel Typ Pflicht Beschreibung
version Zahl Ja Das Dateiformat. Muss 1 sein.
runtime Mapping Ja Die Hauptsprache und ihre Version.
toolchains Liste Nein Zusätzliche Sprachen in derselben Sandbox.
databases Liste Nein PostgreSQL-, MySQL-, MongoDB- und Valkey-Server in der Sandbox.
install Mapping Nein Befehle, die einmal im Workspace-Stamm vor jedem Dienst laufen.
services Mapping Ja Die Prozesse, die installiert, gestartet und getestet werden, nach Namen geordnet. Mindestens einer.
preview Mapping Bei 2+ Diensten Welchen Dienst der Vorschau-Bereich zeigt.
routing Liste Nein Pfadpräfixe auf der Vorschau-Adresse und der Dienst, zu dem jedes führt.
sandbox Mapping Nein Docker oder Kubernetes in der Sandbox.
requests Liste Nein Beispiel-HTTP-Requests für den Tab Requests des Editors.
kendor Mapping Nein Einstellungen nur für Autoren.

Hinweis. Schreibe Versionen als String in Anführungszeichen: version: "3.12", nicht version: 3.12. Ohne Anführungszeichen liest YAML 3.12 als Zahl, und die Datei besteht die Validierung nicht. Das version: 1 der obersten Ebene ist die Ausnahme; es muss die Zahl 1 sein.

runtime

Schlüssel Typ Pflicht Standard Beschreibung
type String Ja Eines von node, php, python, go, java, rust, cpp.
version String Ja Eine Version, die Kendor für diese Sprache anbietet, etwa "22" oder "1.27". Siehe Sprachen und Versionen.
packageManager String Nein Nicht gesetzt npm, pnpm, yarn oder bun. Nur zur Dokumentation vermerkt; was tatsächlich installiert, sind deine install-Befehle.

Die Sprache einer Aufgabe steht fest, sobald sie angelegt ist, ihre Version nicht: Wenn runtime.type der Sprache der Aufgabe entspricht, bestimmt runtime.version, welche Version die Sandbox ausführt.

toolchains

Eine Liste zusätzlicher Sprachen, jeweils mit Compiler, Tools und Language Server im PATH neben der Hauptsprache. Nutze sie für einen Go-Dienst neben einer Node-App oder für Node-Asset-Builds in einem PHP-Projekt.

Schlüssel Typ Pflicht Beschreibung
type String Ja Dieselbe Auswahl wie bei runtime.type.
version String Ja Eine Version, die Kendor für diese Sprache anbietet.

Jede Sprache darf über runtime und toolchains hinweg nur einmal vorkommen.

databases

Eine Liste von Datenbankservern, die in der Sandbox auf 127.0.0.1 laufen und vor jedem Install-Befehl starten. Verbindungsdetails findest du unter Datenbanken in der Sandbox.

Schlüssel Typ Pflicht Standard Beschreibung
type String Ja postgres, mysql, mongodb oder valkey. Jeder Typ höchstens einmal, und nicht postgres und mysql zusammen.
version String Ja "18" für PostgreSQL, "8.4" für MySQL, "8.0" für MongoDB, "9" für Valkey.
name String Nein app PostgreSQL, MySQL und MongoDB. Die Datenbank, die angelegt wird: Kleinbuchstaben, Ziffern, Unterstriche und Bindestriche, beginnend mit einem Buchstaben oder Unterstrich, höchstens 63 Zeichen, und nicht postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema oder sys.
user String Nein kendor PostgreSQL, MySQL und MongoDB. Der Benutzer, als der sich die App verbindet, wenn das Projekt einen eigenen erwartet (postgres://shop:secret@localhost/shop). Buchstaben, Ziffern, Unterstriche und Bindestriche, höchstens 32. Jede Verbindungsvariable verwendet ihn.
password String Nein Nicht gesetzt (MongoDB: kendor) PostgreSQL, MySQL und MongoDB. Das Passwort dieses Benutzers, eine Zeile mit höchstens 128 Zeichen. Kendor trägt user, password und name beim Import aus der .env.example oder docker-compose eines Repositorys ein.
init String Nein Nicht gesetzt PostgreSQL, MySQL und MongoDB. Eine Seed-Datei oder ein Ordner, dessen Seed-Dateien in alphabetischer Reihenfolge laufen, relativ zum Workspace-Stamm: .sql für PostgreSQL und MySQL, .js für MongoDB. Läuft einmal, nachdem die Datenbank angelegt wurde.

install

Befehle, die einmal im Workspace-Stamm laufen, bevor ein Dienst startet. Nutze sie für eine einzelne Installation, die das gesamte Repository abdeckt, etwa pnpm install in einem Monorepo.

Schlüssel Typ Pflicht Beschreibung
commands Liste von Strings Ja Mindestens einer. Sie laufen der Reihe nach; endet einer mit einem Wert ungleich null, werden die folgenden übersprungen.

Die Datenbanken laufen bereits, wenn diese Befehle starten. Lege Migrationen in die migrate-Befehle eines Dienstes statt hierher: Install-Befehle werden bei einem Neustart übersprungen, wenn sich keine Abhängigkeitsdatei geändert hat, neue Migrationsdateien würden also nicht angewendet.

services

Ein Mapping vom Dienstnamen auf den Dienst. Namen beginnen mit einem Kleinbuchstaben und enthalten nur Kleinbuchstaben, Ziffern und Bindestriche, zum Beispiel api oder web-app. Der Name kendor-db ist reserviert. Jeder Dienst läuft in der Sandbox in einem eigenen Prozessfenster.

Schlüssel Typ Pflicht Standard Beschreibung
workDir String Nein . Ordner, in dem die Install-, Dev- und Test-Befehle des Dienstes laufen, relativ zum Workspace-Stamm. Kein führendes / und kein ...
install Mapping Nein commands: eine Liste von mindestens einem Befehl, der Reihe nach in workDir nach dem install der obersten Ebene ausgeführt. Schlägt einer fehl, startet der dev-Befehl des Dienstes nicht.
migrate Mapping Nein commands: eine Liste von mindestens einem Befehl, der die Datenbank auf den neuesten Stand bringt, etwa npx prisma migrate deploy oder php artisan migrate --force. Sie laufen bei jedem Start des Dienstes in workDir, nach dessen Installation und vor dev, mit der Umgebung des Dienstes. Schlägt einer fehl, erscheint der Fehler im Prozess des Dienstes, und dev startet trotzdem.
dev Mapping Nein Der dauerhaft laufende Prozess. Siehe unten.
test Mapping Nein command: der Befehl, den der Tab Tests ausführt. timeout: Sekunden, die er laufen darf, bevor er gestoppt wird, 10 bis 1800 (Standard: 10 Minuten). Erhöhe ihn für große Suites, etwa eine Testdatenbank, deren Aufbau dauert.
publicEnvPrefix String Nein Das Präfix von Variablen, die sich bedenkenlos für Browser-Code freigeben lassen, etwa VITE_. Wird akzeptiert und gespeichert; die Sandbox wertet es nicht aus.

Jeder Dienst braucht mindestens ein dev oder ein test. Ein Dienst nur mit test (und ohne install) bekommt kein Prozessfenster: So sind Einzeldatei-Aufgaben aufgebaut.

Wenn ein Dienst neu startet, wird seine Installation übersprungen, falls sich die Abhängigkeitsdateien in seinem workDir (package.json, Lockfiles, composer.json, requirements.txt, pyproject.toml, go.mod und Ähnliches) nicht geändert haben.

dev

Schlüssel Typ Pflicht Beschreibung
command String Ja Der Befehl, der den Dienst startet, zum Beispiel npm run dev -- --port $PORT.
port Ganzzahl Nein 1 bis 65535. Der Port, auf dem der Dienst lauscht. Zwei Dienste können sich keinen Port teilen.
env.vars Mapping Nein Umgebungsvariablen für diesen Befehl. Die Namen entsprechen [A-Za-z_][A-Za-z0-9_]*; die Werte sind Referenzen, siehe unten.

Kendor setzt diese Variablen für jeden Dev-Befehl, und sie überschreiben alles in env.vars:

Variable Wert
HOST 0.0.0.0
PORT Der port des Dienstes, sofern er einen hat.
KENDOR_PUBLIC_HOST Der öffentliche Vorschau-Hostname der Sandbox.
KENDOR_VITE_ORIGIN Der öffentliche Origin des Dienstes: die Vorschau-Adresse für den Vorschau-Dienst oder die eigene Port-Adresse des Dienstes für jeden anderen Dienst mit Port. Wird vom Plugin @kendordev/vite gelesen.

Binde deinen Server an $HOST und $PORT (oder 0.0.0.0 und den deklarierten Port), damit die Vorschau ihn erreichen kann. Browser-Code, der http://localhost:<port> aufruft, wird an diesen Port in der Sandbox geleitet; siehe localhost in der Vorschau.

Referenzen auf Umgebungsvariablen

Ein Wert in env.vars muss eine von vier Formen haben. Alles andere besteht die Validierung nicht.

Form Beispiel Wird aufgelöst zu
routing.<service>.url routing.api.url Die öffentliche URL dieses Dienstes: die Vorschau-Adresse plus der längste routing-Pfad des Dienstes. Nur die Vorschau-Adresse, wenn der Pfad des Dienstes / ist oder er keine Route hat. Der Dienst muss existieren.
databases.<type>.url databases.postgres.url Die Verbindungs-URL einer unter databases deklarierten Datenbank.
vars.<NAME> vars.sessionId Ein Wert, den Kendor liefert: assessmentId, challengeId oder sessionId. Andere Namen bestehen die Validierung nicht.
lit:<text> lit:debug Der Text nach lit:, unverändert.

Datenbanken setzen außerdem eigene Variablen, etwa DATABASE_URL und REDIS_URL, für jeden Prozess in der Sandbox. databases.<type>.url brauchst du nur, wenn dein Code einen anderen Namen liest.

preview

Schlüssel Typ Pflicht Beschreibung
service String Ja, wenn preview vorhanden ist Der Dienst, dessen Dev-Server der Vorschau-Bereich zeigt. Er muss existieren.

preview ist Pflicht, sobald es mehr als einen Dienst gibt. Bei einem einzigen Dienst ist dieser die Vorschau. Ein Projekt, dessen Dienste keinen dev-Befehl haben, hat keine Vorschau, nur ein Terminal.

routing

Eine Liste von Routen auf der Vorschau-Adresse der Sandbox. Jede Anfrage geht an die Route mit dem längsten passenden Pfadpräfix. Der vollständige Pfad wird weitergereicht, ein Dienst, der unter /api geroutet ist, erhält also /api/products, nicht /products.

Schlüssel Typ Pflicht Beschreibung
path String Ja Beginnt mit /. Füge eine /-Route als Auffangroute hinzu.
service String Ja Ein existierender Dienst. Routen zu einem Dienst ohne dev.port werden übersprungen.

Sind Routen deklariert, zeigt die Vorschau eine kurze Warteseite, bis jeder gerouteten Dienst Verbindungen annimmt. Siehe Multi-Service-Apps.

sandbox

Lässt die Sandbox eigene Container-Tools ausführen.

Schlüssel Typ Standard Beschreibung
containers boolean false Ein Docker-Daemon in der Sandbox, mit docker, docker compose und buildx.
kubernetes boolean false Ein Ein-Knoten-k3s-Cluster, der beim Booten startet, mit kubectl und helm. Schaltet auch containers ein.

Beides gibt der Sandbox mehr Speicher und CPU. Die Vorschau kann Ports öffnen, die mit docker run -p oder Compose veröffentlicht wurden, sowie kubectl port-forward mit --address 0.0.0.0. Eine Konfiguration mit containers oder kubernetes darf keinen test-Befehl definieren, im Tab Tests gibt es also nichts auszuführen; nutze sie für Aufgaben, die du durch Lesen der Arbeit bewertest. Die Preisseite führt Container-Umgebungen im Enterprise-Tarif auf.

kendor.yaml
version: 1
runtime:
  type: node
  version: "22"
sandbox:
  containers: true
services:
  app:
    install:
      commands:
        - npm ci
    dev:
      command: docker compose up

requests

Beispiel-HTTP-Requests, die versandbereit im Tab Requests des Editors erscheinen. Requests werden aus der Sandbox heraus gesendet, localhost funktioniert also wie mit curl im Terminal. Sie verändern nie, wie die Sandbox startet.

Schlüssel Typ Pflicht Standard Beschreibung
name String Ja Die Bezeichnung in der Liste.
method String Nein GET GET, POST, PUT, PATCH, DELETE, HEAD oder OPTIONS.
url String Ja Eine vollständige URL wie http://localhost:3000/api/todos oder ein Pfad wie /api/todos, der an den Port des Vorschau-Dienstes gesendet wird.
headers Mapping Nein Header-Name auf Wert.
body String Nein Der Request-Body.

Ein Beispiel mit einem Fehler wird im Tab ausgelassen; die anderen werden weiterhin angezeigt.

kendor

Einstellungen nur für Autoren. Ein Kandidat kann sie nicht ändern. Der Block akzeptiert zusätzliche Schlüssel ohne Fehler.

Schlüssel Typ Beschreibung
gradeService String Der Dienst, dessen test.command der Tab Tests ausführt. Standard ist der Vorschau-Dienst. Muss einen existierenden Dienst benennen.
gradeServices Liste von Strings Mehrere Dienste, deren Test-Befehle der Tab Tests ausführt, jeweils in ihrem eigenen workDir. Die Ergebnisse werden als service › test aufgelistet. Jeder genannte Dienst muss existieren und ein test haben. Verwende entweder dies oder gradeService, nicht beides.

Der Block enthält außerdem Schlüssel, die der Vorlagenkatalog von Kendor selbst nutzt, um seine Vorlagen zu beschreiben: title, entryFile, order, type, difficulty, category, tags, editablePaths, readonlyPaths und solutionDir. Sie haben keine Wirkung auf deine Aufgabe: Lege schreibgeschützte Pfade stattdessen unter Einstellungen im Aufgaben-Editor fest (siehe So führen Kandidaten Tests aus).

Validierungsregeln

Eine Datei wird nur gespeichert, wenn alle folgenden Punkte zutreffen:

  • version ist 1, und runtime sowie mindestens ein Dienst sind vorhanden.
  • Keine unbekannten Schlüssel außerhalb von kendor.
  • Dienstnamen entsprechen ^[a-z][a-z0-9-]*$, und keiner heißt kendor-db.
  • Jeder Dienst hat ein dev oder ein test.
  • workDir und databases[].init sind relative Pfade innerhalb des Workspace: kein führendes /, kein Laufwerksbuchstabe, kein ...
  • Zwei Dienste verwenden nicht denselben dev.port.
  • preview.service benennt einen existierenden Dienst, und preview ist vorhanden, wenn es zwei oder mehr Dienste gibt.
  • Jedes routing[].service benennt einen existierenden Dienst, und jeder path beginnt mit /.
  • Jeder env.vars-Wert verwendet eine der vier Referenzformen; routing.<service>.url benennt einen existierenden Dienst, databases.<type>.url benennt eine deklarierte Datenbank, und vars.<NAME> ist assessmentId, challengeId oder sessionId.
  • Jede Sprache kommt über runtime und toolchains hinweg einmal vor, und jeder Datenbanktyp einmal.
  • Höchstens eine SQL-Datenbank: postgres oder mysql, nicht beide.
  • name, user, password und init kommen nur bei einer postgres-, mysql- oder mongodb-Datenbank vor, und name folgt der oben genannten Namensregel.
  • kendor.gradeService und jeder Eintrag von kendor.gradeServices benennen existierende Dienste, Einträge von gradeServices haben ein test, und die beiden Schlüssel werden nicht zusammen verwendet.
  • Bei sandbox.containers oder sandbox.kubernetes hat kein Dienst ein test, und weder gradeService noch gradeServices ist gesetzt.
  • Jede Sprach- und Datenbankversion ist eine, die Kendor anbietet. Versionen, die für neue Aufgaben nicht mehr angeboten werden, bestehen weiterhin, sodass eine Aufgabe, die eine solche nutzt, weiter gespeichert werden kann.
War dieser Artikel hilfreich?