Référence de kendor.yaml
Toutes les clés acceptées par kendor.yaml, de runtime et services à routing, databases et sandbox, avec leurs types, leurs valeurs par défaut et les règles vérifiées à l’enregistrement.
kendor.yaml se trouve à la racine du projet d’un exercice et indique au bac à sable ce qu’il doit
exécuter : un langage et sa version, éventuellement d’autres langages et des bases de données, et un
ou plusieurs services avec leurs commandes d’installation, de dev et de test. Seules version,
runtime et services sont obligatoires. Kendor vérifie tout le fichier à l’enregistrement, et un
fichier comportant des erreurs n’est pas enregistré.
Où se trouve le fichier et quand il s’applique
Le fichier est kendor.yaml, à la racine de l’espace de travail. Dans un zip importé ou un dépôt
importé, Kendor accepte aussi l’orthographe kendor.yml.
Dans l’éditeur d’exercice, ouvrez Paramètres et choisissez Configurer l’exécution…. La boîte
de dialogue Configuration d’exécution comporte un onglet Formulaire et un onglet YAML
brut ; l’enregistrement écrit kendor.yaml et redémarre l’aperçu. Si vous modifiez plutôt le
fichier à la main, une bannière kendor.yaml modifié apparaît, car le bac à sable exécute toujours
la configuration précédente tant que vous ne choisissez pas Enregistrer et redémarrer.
À l’enregistrement, Kendor exécute les vérifications listées sous
Règles de validation et contrôle aussi que chaque version de langage et de
base de données fait partie de celles que Kendor propose. Chaque problème est signalé avec son
chemin dans le fichier, par exemple services.web.dev.port.
La copie de kendor.yaml à l’intérieur d’un bac à sable en cours d’exécution est régénérée à partir
de la configuration enregistrée à chaque démarrage du bac à sable : elle montre donc toujours ce que
le bac à sable exécute.
Astuce. Commencez le fichier par
# yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Les éditeurs qui utilisent
le serveur de langage YAML proposent alors l’autocomplétion et des erreurs en ligne pour chaque clé
de cette page.
Ce que les candidats peuvent modifier
Un candidat peut modifier kendor.yaml dans son propre espace de travail. Seules quatre clés de
premier niveau sont lues dans sa copie : install, services, preview et routing. Ses
modifications s’appliquent au redémarrage du bac à sable, et seulement si le fichier fusionné passe
toujours la validation ; sinon, votre configuration reste en place. runtime, toolchains,
databases, sandbox et kendor proviennent toujours de votre fichier, tout comme les commandes de
test : tout test écrit par un candidat est ignoré, et vos commandes test sont conservées sur les
services que vous avez définis.
Un exemple complet
Une API Node.js et un frontend Vite, avec PostgreSQL et Valkey, plus un worker Python :
# 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: apiClés de premier niveau
Les clés inconnues sont rejetées partout dans le fichier, sauf à l’intérieur de kendor.
| Clé | Type | Obligatoire | Description |
|---|---|---|---|
version |
nombre | Oui | Le format du fichier. Doit valoir 1. |
runtime |
mapping | Oui | Le langage principal et sa version. |
toolchains |
liste | Non | Langages supplémentaires dans le même bac à sable. |
databases |
liste | Non | Serveurs PostgreSQL, MySQL, MongoDB et Valkey dans le bac à sable. |
install |
mapping | Non | Commandes exécutées une fois à la racine de l’espace de travail avant tout service. |
services |
mapping | Oui | Les processus à installer, démarrer et tester, indexés par nom. Au moins un. |
preview |
mapping | Quand il y a 2 services ou plus | Le service que le volet d’aperçu affiche. |
routing |
liste | Non | Les préfixes de chemin de l’adresse d’aperçu et le service vers lequel va chacun. |
sandbox |
mapping | Non | Docker ou Kubernetes dans le bac à sable. |
requests |
liste | Non | Exemples de requêtes HTTP pour l’onglet Requêtes de l’éditeur. |
kendor |
mapping | Non | Paramètres réservés aux auteurs. |
Remarque. Écrivez les versions comme des chaînes entre guillemets : version: "3.12", et non
version: 3.12. Sans guillemets, YAML lit 3.12 comme un nombre et le fichier échoue à la
validation. Le version: 1 de premier niveau fait exception : il doit être le nombre 1.
runtime
| Clé | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
type |
chaîne | Oui | L’un de node, php, python, go, java, rust, cpp. |
|
version |
chaîne | Oui | Une version que Kendor propose pour ce langage, comme "22" ou "1.27". Voir Langages et versions. |
|
packageManager |
chaîne | Non | Non défini | npm, pnpm, yarn ou bun. Enregistré à titre indicatif ; ce qui installe réellement, ce sont vos commandes install. |
Le langage d’un exercice est fixé à sa création, mais pas sa version : quand runtime.type est le
langage de l’exercice, runtime.version détermine la version qu’exécute le bac à sable.
toolchains
Une liste de langages supplémentaires, chacun avec son compilateur, ses outils et son serveur de
langage dans le PATH à côté du principal. Utilisez-la pour un service Go à côté d’une application
Node, ou Node pour les builds d’assets dans un projet PHP.
| Clé | Type | Obligatoire | Description |
|---|---|---|---|
type |
chaîne | Oui | Les mêmes choix que runtime.type. |
version |
chaîne | Oui | Une version que Kendor propose pour ce langage. |
Chaque langage ne peut apparaître qu’une fois dans runtime et toolchains réunis.
databases
Une liste de serveurs de bases de données qui s’exécutent dans le bac à sable sur 127.0.0.1 et
démarrent avant toute commande d’installation. Voir
Bases de données dans le bac à sable pour les détails de connexion.
| Clé | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
type |
chaîne | Oui | postgres, mysql, mongodb ou valkey. Chaque type au plus une fois, et pas à la fois postgres et mysql. |
|
version |
chaîne | Oui | "18" pour PostgreSQL, "8.4" pour MySQL, "8.0" pour MongoDB, "9" pour Valkey. |
|
name |
chaîne | Non | app |
PostgreSQL, MySQL et MongoDB. La base à créer : lettres minuscules, chiffres, tirets bas et traits d’union, en commençant par une lettre ou un tiret bas, 63 caractères au plus, et différent de postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema ou sys. |
user |
chaîne | Non | kendor |
PostgreSQL, MySQL et MongoDB. L’utilisateur avec lequel l’application se connecte, quand le projet attend le sien (postgres://shop:secret@localhost/shop). Lettres, chiffres, tirets bas et traits d’union, 32 au plus. Toutes les variables de connexion l’utilisent. |
password |
chaîne | Non | Non défini (MongoDB : kendor) |
PostgreSQL, MySQL et MongoDB. Le mot de passe de cet utilisateur, une seule ligne de 128 caractères au plus. Kendor renseigne user, password et name à partir du .env.example ou du docker-compose d’un dépôt quand vous l’importez. |
init |
chaîne | Non | Non défini | PostgreSQL, MySQL et MongoDB. Un fichier de seed, ou un dossier dont les fichiers de seed s’exécutent dans l’ordre des noms, relatif à la racine de l’espace de travail : .sql pour PostgreSQL et MySQL, .js pour MongoDB. S’exécute une seule fois, après la création de la base. |
install
Des commandes qui s’exécutent une fois à la racine de l’espace de travail, avant le démarrage de tout
service. Utilisez-les pour une installation unique couvrant tout le dépôt, comme pnpm install dans
un monorepo.
| Clé | Type | Obligatoire | Description |
|---|---|---|---|
commands |
liste de chaînes | Oui | Au moins une. Elles s’exécutent dans l’ordre ; si l’une se termine avec un code non nul, les suivantes sont ignorées. |
Les bases de données sont déjà en cours d’exécution quand ces commandes démarrent. Placez les
migrations dans les commandes migrate d’un service plutôt qu’ici : les commandes d’installation
sont ignorées lors d’un redémarrage quand aucun fichier de dépendances n’a changé, et les nouveaux
fichiers de migration ne seraient donc pas appliqués.
services
Un mapping entre nom de service et service. Les noms commencent par une lettre minuscule et ne
contiennent que des lettres minuscules, des chiffres et des traits d’union, par exemple api ou
web-app. Le nom kendor-db est réservé. Chaque service s’exécute dans sa propre fenêtre de
processus dans le bac à sable.
| Clé | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
workDir |
chaîne | Non | . |
Dossier dans lequel s’exécutent les commandes d’installation, dev et de test du service, relatif à la racine de l’espace de travail. Pas de / initial ni de ... |
install |
mapping | Non | commands : une liste d’au moins une commande, exécutées dans l’ordre dans workDir après l’install de premier niveau. Si l’une échoue, la commande dev du service ne démarre pas. |
|
migrate |
mapping | Non | commands : une liste d’au moins une commande qui met la base de données à jour, comme npx prisma migrate deploy ou php artisan migrate --force. Elles s’exécutent dans workDir à chaque démarrage du service, après son installation et avant dev, avec l’environnement du service. Si l’une échoue, l’erreur s’affiche dans le processus du service et dev démarre quand même. |
|
dev |
mapping | Non | Le processus de longue durée. Voir plus bas. | |
test |
mapping | Non | command : la commande qu’exécute l’onglet Tests. timeout : durée maximale en secondes avant l’arrêt, de 10 à 1800 (par défaut : 10 minutes). Augmentez-la pour les grosses suites, par exemple une base de test longue à préparer. |
|
publicEnvPrefix |
chaîne | Non | Le préfixe des variables qu’on peut exposer sans risque au code navigateur, comme VITE_. Accepté et stocké ; le bac à sable n’en tient pas compte. |
Chaque service a besoin d’au moins un dev ou un test. Un service avec seulement test (et sans
install) n’obtient pas de fenêtre de processus : c’est ainsi que sont configurés les exercices à
fichier unique.
Quand un service redémarre, son installation est ignorée si les fichiers de dépendances de son
workDir (package.json, fichiers de verrouillage, composer.json, requirements.txt,
pyproject.toml, go.mod et similaires) n’ont pas changé.
dev
| Clé | Type | Obligatoire | Description |
|---|---|---|---|
command |
chaîne | Oui | La commande qui démarre le service, par exemple npm run dev -- --port $PORT. |
port |
entier | Non | De 1 à 65535. Le port sur lequel le service écoute. Deux services ne peuvent pas partager un port. |
env.vars |
mapping | Non | Variables d’environnement de cette commande. Les noms correspondent à [A-Za-z_][A-Za-z0-9_]* ; les valeurs sont des références, décrites plus bas. |
Kendor définit ces variables pour chaque commande dev, et elles l’emportent sur tout ce qui figure
dans env.vars :
| Variable | Valeur |
|---|---|
HOST |
0.0.0.0 |
PORT |
Le port du service, quand il en a un. |
KENDOR_PUBLIC_HOST |
Le nom d’hôte d’aperçu public du bac à sable. |
KENDOR_VITE_ORIGIN |
L’origine publique du service : l’adresse d’aperçu pour le service d’aperçu, ou l’adresse du port propre du service pour tout autre service doté d’un port. Lue par le plugin @kendordev/vite. |
Liez votre serveur à $HOST et $PORT (ou à 0.0.0.0 et au port déclaré) pour que l’aperçu puisse
l’atteindre. Le code navigateur qui appelle http://localhost:<port> est envoyé vers ce port dans le
bac à sable ; voir localhost dans l’aperçu.
Références de variables d’environnement
Une valeur dans env.vars doit utiliser l’une des quatre formes. Toute autre échoue à la
validation.
| Forme | Exemple | Se résout en |
|---|---|---|
routing.<service>.url |
routing.api.url |
L’URL publique de ce service : l’adresse d’aperçu suivie du plus long chemin routing du service. L’adresse d’aperçu seule quand le chemin du service est / ou qu’il n’a pas de route. Le service doit exister. |
databases.<type>.url |
databases.postgres.url |
L’URL de connexion d’une base de données déclarée sous databases. |
vars.<NAME> |
vars.sessionId |
Une valeur fournie par Kendor : assessmentId, challengeId ou sessionId. Les autres noms échouent à la validation. |
lit:<text> |
lit:debug |
Le texte après lit:, tel quel. |
Les bases de données définissent aussi leurs propres variables, comme DATABASE_URL et REDIS_URL,
pour chaque processus du bac à sable. Vous n’avez besoin de databases.<type>.url que lorsque votre
code lit un autre nom.
preview
| Clé | Type | Obligatoire | Description |
|---|---|---|---|
service |
chaîne | Oui, quand preview est présent |
Le service dont le serveur de dev est affiché par le volet d’aperçu. Il doit exister. |
preview est obligatoire quand il y a plus d’un service. Avec un seul service, c’est lui l’aperçu.
Un projet dont les services n’ont pas de commande dev n’a pas d’aperçu, seulement un terminal.
routing
Une liste de routes sur l’adresse d’aperçu du bac à sable. Chaque requête va vers la route dont le
préfixe de chemin correspond le plus long. Le chemin complet est transmis : un service routé sur
/api reçoit donc /api/products, et non /products.
| Clé | Type | Obligatoire | Description |
|---|---|---|---|
path |
chaîne | Oui | Commence par /. Ajoutez une route / comme route par défaut. |
service |
chaîne | Oui | Un service existant. Les routes vers un service sans dev.port sont ignorées. |
Quand des routes sont déclarées, l’aperçu affiche une courte page d’attente jusqu’à ce que chaque service routé accepte des connexions. Voir Applications à plusieurs services.
sandbox
Permet au bac à sable d’exécuter ses propres outils de conteneurs.
| Clé | Type | Par défaut | Description |
|---|---|---|---|
containers |
booléen | false |
Un démon Docker dans le bac à sable, avec docker, docker compose et buildx. |
kubernetes |
booléen | false |
Un cluster k3s à nœud unique démarré au boot, avec kubectl et helm. Active aussi containers. |
L’une ou l’autre donne au bac à sable davantage de mémoire et de CPU. L’aperçu peut ouvrir les ports
publiés par docker run -p ou Compose, et par kubectl port-forward avec --address 0.0.0.0. Une
configuration avec containers ou kubernetes ne peut définir aucune commande test : il n’y a donc
rien à lancer depuis l’onglet Tests ; réservez-la aux exercices que vous évaluez en lisant le
travail. La page des tarifs liste les environnements de conteneurs dans l’offre Enterprise.
version: 1
runtime:
type: node
version: "22"
sandbox:
containers: true
services:
app:
install:
commands:
- npm ci
dev:
command: docker compose uprequests
Des exemples de requêtes HTTP qui apparaissent, prêts à être envoyés, dans l’onglet Requêtes de
l’éditeur. Les requêtes sont envoyées depuis l’intérieur du bac à sable : localhost fonctionne donc
comme avec curl dans le terminal. Elles ne changent jamais la façon dont le bac à sable démarre.
| Clé | Type | Obligatoire | Par défaut | Description |
|---|---|---|---|---|
name |
chaîne | Oui | Le libellé affiché dans la liste. | |
method |
chaîne | Non | GET |
GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS. |
url |
chaîne | Oui | Une URL complète comme http://localhost:3000/api/todos, ou un chemin comme /api/todos, qui est envoyé au port du service d’aperçu. |
|
headers |
mapping | Non | Nom d’en-tête vers valeur. | |
body |
chaîne | Non | Le corps de la requête. |
Un exemple comportant une erreur est exclu de l’onglet ; les autres s’affichent quand même.
kendor
Paramètres réservés aux auteurs. Un candidat ne peut pas les modifier. Ce bloc accepte des clés supplémentaires sans erreur.
| Clé | Type | Description |
|---|---|---|
gradeService |
chaîne | Le service dont l’onglet Tests exécute la test.command. Par défaut, le service d’aperçu. Doit désigner un service existant. |
gradeServices |
liste de chaînes | Plusieurs services dont l’onglet Tests exécute les commandes de test, chacune dans son propre workDir. Les résultats sont listés sous la forme service › test. Chaque service nommé doit exister et avoir un test. Utilisez soit cette clé, soit gradeService, pas les deux. |
Le bloc contient aussi des clés que le catalogue de modèles de Kendor utilise pour décrire ses
modèles : title, entryFile, order, type, difficulty, category, tags, editablePaths,
readonlyPaths et solutionDir. Elles n’ont aucun effet sur votre exercice : définissez plutôt les
chemins en lecture seule dans les Paramètres de l’éditeur d’épreuve (voir
Comment les candidats lancent les tests).
Règles de validation
Un fichier n’est enregistré que si toutes ces conditions sont réunies :
versionvaut1, etruntimeainsi qu’au moins un service sont présents.- Aucune clé inconnue en dehors de
kendor. - Les noms de services correspondent à
^[a-z][a-z0-9-]*$et aucun n’estkendor-db. - Chaque service a un
devou untest. workDiretdatabases[].initsont des chemins relatifs à l’intérieur de l’espace de travail : pas de/initial, pas de lettre de lecteur, pas de...- Deux services n’utilisent pas le même
dev.port. preview.servicedésigne un service existant, etpreviewest présent quand il y a deux services ou plus.- Chaque
routing[].servicedésigne un service existant, et chaquepathcommence par/. - Chaque valeur d’
env.varsutilise l’une des quatre formes de référence ;routing.<service>.urldésigne un service existant,databases.<type>.urldésigne une base de données déclarée, etvars.<NAME>vautassessmentId,challengeIdousessionId. - Chaque langage apparaît une fois dans
runtimeettoolchainsréunis, et chaque type de base de données une fois. - Au plus une base de données SQL :
postgresoumysql, pas les deux. name,user,passwordetinitn’apparaissent que sur une base de donnéespostgres,mysqloumongodb, etnamerespecte la règle de nommage ci-dessus.kendor.gradeServiceet chaque entrée dekendor.gradeServicesdésignent des services existants, les entrées degradeServicesont untest, et les deux clés ne sont pas utilisées ensemble.- Avec
sandbox.containersousandbox.kubernetes, aucun service n’a detestet nigradeServicenigradeServicesn’est défini. - Chaque version de langage et de base de données fait partie de celles que Kendor propose. Les versions qui ne sont plus proposées pour les nouveaux exercices passent quand même : un exercice qui en utilise une continue donc de s’enregistrer.