kendor.yaml-Referenz
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:
# 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: apiSchlü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.
version: 1
runtime:
type: node
version: "22"
sandbox:
containers: true
services:
app:
install:
commands:
- npm ci
dev:
command: docker compose uprequests
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:
versionist1, undruntimesowie mindestens ein Dienst sind vorhanden.- Keine unbekannten Schlüssel außerhalb von
kendor. - Dienstnamen entsprechen
^[a-z][a-z0-9-]*$, und keiner heißtkendor-db. - Jeder Dienst hat ein
devoder eintest. workDirunddatabases[].initsind relative Pfade innerhalb des Workspace: kein führendes/, kein Laufwerksbuchstabe, kein...- Zwei Dienste verwenden nicht denselben
dev.port. preview.servicebenennt einen existierenden Dienst, undpreviewist vorhanden, wenn es zwei oder mehr Dienste gibt.- Jedes
routing[].servicebenennt einen existierenden Dienst, und jederpathbeginnt mit/. - Jeder
env.vars-Wert verwendet eine der vier Referenzformen;routing.<service>.urlbenennt einen existierenden Dienst,databases.<type>.urlbenennt eine deklarierte Datenbank, undvars.<NAME>istassessmentId,challengeIdodersessionId. - Jede Sprache kommt über
runtimeundtoolchainshinweg einmal vor, und jeder Datenbanktyp einmal. - Höchstens eine SQL-Datenbank:
postgresodermysql, nicht beide. name,user,passwordundinitkommen nur bei einerpostgres-,mysql- odermongodb-Datenbank vor, undnamefolgt der oben genannten Namensregel.kendor.gradeServiceund jeder Eintrag vonkendor.gradeServicesbenennen existierende Dienste, Einträge vongradeServiceshaben eintest, und die beiden Schlüssel werden nicht zusammen verwendet.- Bei
sandbox.containersodersandbox.kuberneteshat kein Dienst eintest, und wedergradeServicenochgradeServicesist 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.