Riferimento di kendor.yaml
Tutte le chiavi accettate da kendor.yaml, da runtime e services a routing, database e sandbox, con tipi, valori predefiniti e regole controllate al salvataggio.
kendor.yaml si trova nella radice del progetto di una sfida e dice alla sandbox che cosa eseguire:
un linguaggio e una versione, eventuali linguaggi e database aggiuntivi, e uno o più servizi con i
rispettivi comandi di installazione, di sviluppo e di test. Solo version, runtime e services
sono obbligatori. Kendor controlla l'intero file quando lo salvi, e un file con errori non viene salvato.
Dove si trova il file e quando si applica
Il file è kendor.yaml nella radice del workspace. In uno zip caricato o in un repository
importato, Kendor accetta anche la grafia kendor.yml.
Nell'editor della sfida apri Impostazioni e scegli Configura runtime…. La finestra
Configurazione runtime ha una scheda Modulo e una scheda YAML grezzo; il salvataggio scrive
kendor.yaml e riavvia l'anteprima. Se invece modifichi il file a mano, compare un banner
kendor.yaml modificato, perché la sandbox continua a eseguire la configurazione precedente finché
non scegli Salva e riavvia.
Quando salvi, Kendor esegue i controlli elencati in Regole di validazione e
verifica anche che ogni versione di linguaggio e di database sia una di quelle offerte da Kendor.
Ogni problema viene segnalato con il suo percorso nel file, ad esempio services.web.dev.port.
La copia di kendor.yaml dentro una sandbox in esecuzione viene rigenerata dalla configurazione
salvata a ogni avvio della sandbox, quindi mostra sempre ciò che la sandbox sta eseguendo.
Suggerimento. Inizia il file con
# yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Gli editor che usano il
language server YAML offrono così il completamento automatico e gli errori in linea per ogni chiave
descritta in questa pagina.
Che cosa possono modificare i candidati
Un candidato può modificare kendor.yaml nel proprio workspace. Dalla sua copia vengono lette solo
quattro chiavi di primo livello: install, services, preview e routing. Le modifiche si
applicano al riavvio della sandbox, e solo se il file risultante dall'unione supera ancora la
validazione; altrimenti la tua configurazione resta al suo posto. runtime, toolchains,
databases, sandbox e kendor provengono sempre dal tuo file, e lo stesso vale per i comandi di
test: qualsiasi test scritto da un candidato viene scartato, e i tuoi comandi test restano sui
servizi che hai definito.
Un esempio completo
Un'API Node.js e un frontend Vite, con PostgreSQL e Valkey, più 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: apiChiavi di primo livello
Le chiavi sconosciute vengono rifiutate in qualsiasi punto del file, tranne dentro kendor.
| Chiave | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
version |
numero | Sì | Il formato del file. Deve essere 1. |
runtime |
mappa | Sì | Il linguaggio principale e la sua versione. |
toolchains |
lista | No | Linguaggi aggiuntivi nella stessa sandbox. |
databases |
lista | No | Server PostgreSQL, MySQL, MongoDB e Valkey dentro la sandbox. |
install |
mappa | No | Comandi eseguiti una volta nella radice del workspace prima di qualsiasi servizio. |
services |
mappa | Sì | I processi da installare, avviare e testare, indicizzati per nome. Almeno uno. |
preview |
mappa | Quando i servizi sono 2 o più | Quale servizio mostra il riquadro di anteprima. |
routing |
lista | No | I prefissi di percorso sull'indirizzo dell'anteprima e il servizio a cui porta ciascuno. |
sandbox |
mappa | No | Docker o Kubernetes dentro la sandbox. |
requests |
lista | No | Richieste HTTP di esempio per la scheda Richieste dell'editor. |
kendor |
mappa | No | Impostazioni riservate a chi crea la sfida. |
Nota. Scrivi le versioni come stringhe tra virgolette: version: "3.12", non version: 3.12.
Senza virgolette, YAML legge 3.12 come numero e il file non supera la validazione. Il version: 1
di primo livello è l'eccezione: deve essere il numero 1.
runtime
| Chiave | Tipo | Obbligatoria | Predefinito | Descrizione |
|---|---|---|---|---|
type |
stringa | Sì | Uno tra node, php, python, go, java, rust, cpp. |
|
version |
stringa | Sì | Una versione che Kendor offre per quel linguaggio, ad esempio "22" o "1.27". Vedi Linguaggi e versioni. |
|
packageManager |
stringa | No | Non impostato | npm, pnpm, yarn o bun. Registrato come riferimento; ciò che installa davvero sono i tuoi comandi install. |
Il linguaggio di una sfida è fissato alla creazione, ma la versione no: quando runtime.type è il
linguaggio della sfida, runtime.version decide quale versione esegue la sandbox.
toolchains
Una lista di linguaggi aggiuntivi, ciascuno con il suo compilatore, i suoi strumenti e il suo language
server nel PATH accanto a quello principale. Usala per un servizio Go accanto a un'app Node, o per
Node nelle build degli asset di un progetto PHP.
| Chiave | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
type |
stringa | Sì | Stesse scelte di runtime.type. |
version |
stringa | Sì | Una versione che Kendor offre per quel linguaggio. |
Ogni linguaggio può comparire una sola volta tra runtime e toolchains.
databases
Una lista di server di database che girano dentro la sandbox su 127.0.0.1 e partono prima di
qualsiasi comando di installazione. Per i dettagli di connessione vedi Database nella sandbox.
| Chiave | Tipo | Obbligatoria | Predefinito | Descrizione |
|---|---|---|---|---|
type |
stringa | Sì | postgres, mysql, mongodb o valkey. Ogni tipo al massimo una volta, e non sia postgres sia mysql. |
|
version |
stringa | Sì | "18" per PostgreSQL, "8.4" per MySQL, "8.0" per MongoDB, "9" per Valkey. |
|
name |
stringa | No | app |
PostgreSQL, MySQL e MongoDB. Il database da creare: lettere minuscole, cifre, trattini bassi e trattini, che inizi con una lettera o un trattino basso, al massimo 63 caratteri, e diverso da postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema e sys. |
user |
stringa | No | kendor |
PostgreSQL, MySQL e MongoDB. L'utente con cui si collega l'app, quando il progetto ne prevede uno proprio (postgres://shop:secret@localhost/shop). Lettere, cifre, trattini bassi e trattini, al massimo 32. Ogni variabile di connessione lo usa. |
password |
stringa | No | Non impostata (MongoDB: kendor) |
PostgreSQL, MySQL e MongoDB. La password di quell'utente, su una sola riga di al massimo 128 caratteri. Kendor compila user, password e name a partire dal .env.example o dal docker-compose di un repository quando lo importi. |
init |
stringa | No | Non impostato | PostgreSQL, MySQL e MongoDB. Un file di seed, o una cartella i cui file di seed vengono eseguiti in ordine di nome, relativo alla radice del workspace: .sql per PostgreSQL e MySQL, .js per MongoDB. Viene eseguito una volta, dopo la creazione del database. |
install
Comandi eseguiti una volta nella radice del workspace, prima dell'avvio di qualsiasi servizio. Usalo
per un'unica installazione che copra l'intero repository, come pnpm install in un monorepo.
| Chiave | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
commands |
lista di stringhe | Sì | Almeno una. Vengono eseguiti in ordine; se uno termina con codice diverso da zero, quelli successivi vengono saltati. |
I database sono già in esecuzione quando questi comandi partono. Metti le migrazioni nei comandi
migrate di un servizio e non qui: i comandi di installazione vengono saltati a un riavvio quando
nessun file delle dipendenze è cambiato, quindi i nuovi file di migrazione non verrebbero applicati.
services
Una mappa dal nome del servizio al servizio. I nomi iniziano con una lettera minuscola e contengono
solo lettere minuscole, cifre e trattini, ad esempio api o web-app. Il nome kendor-db è
riservato. Ogni servizio gira in una propria finestra di processo nella sandbox.
| Chiave | Tipo | Obbligatoria | Predefinito | Descrizione |
|---|---|---|---|---|
workDir |
stringa | No | . |
Cartella in cui vengono eseguiti i comandi di installazione, di sviluppo e di test del servizio, relativa alla radice del workspace. Senza / iniziale e senza ... |
install |
mappa | No | commands: una lista di almeno un comando, eseguiti in ordine in workDir dopo l'install di primo livello. Se uno fallisce, il comando dev del servizio non parte. |
|
migrate |
mappa | No | commands: una lista di almeno un comando che porta il database allo stato aggiornato, come npx prisma migrate deploy o php artisan migrate --force. Vengono eseguiti in workDir a ogni avvio del servizio, dopo l'installazione e prima di dev, con l'ambiente del servizio. Se uno fallisce, l'errore compare nel processo del servizio e dev parte comunque. |
|
dev |
mappa | No | Il processo di lunga durata. Vedi sotto. | |
test |
mappa | No | command: il comando che esegue la scheda Test. timeout: secondi che può durare prima di essere fermato, da 10 a 1800 (predefinito: 10 minuti). Aumentalo per suite grandi, come un database di test lento da preparare. |
|
publicEnvPrefix |
stringa | No | Il prefisso delle variabili che si possono esporre in sicurezza al codice del browser, come VITE_. Accettato e memorizzato; la sandbox non ne tiene conto. |
Ogni servizio ha bisogno almeno di un dev o di un test. Un servizio con solo test (e senza
install) non ha una finestra di processo: è così che sono impostate le sfide a file singolo.
Quando un servizio viene riavviato, la sua installazione viene saltata se i file delle dipendenze nel
suo workDir (package.json, lockfile, composer.json, requirements.txt, pyproject.toml,
go.mod e simili) non sono cambiati.
dev
| Chiave | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
command |
stringa | Sì | Il comando che avvia il servizio, ad esempio npm run dev -- --port $PORT. |
port |
intero | No | Da 1 a 65535. La porta su cui è in ascolto il servizio. Due servizi non possono condividere una porta. |
env.vars |
mappa | No | Variabili d'ambiente per questo comando. I nomi corrispondono a [A-Za-z_][A-Za-z0-9_]*; i valori sono riferimenti, descritti sotto. |
Kendor imposta queste variabili per ogni comando dev, e prevalgono su qualsiasi cosa in env.vars:
| Variabile | Valore |
|---|---|
HOST |
0.0.0.0 |
PORT |
La port del servizio, quando ne ha una. |
KENDOR_PUBLIC_HOST |
Il nome host pubblico dell'anteprima della sandbox. |
KENDOR_VITE_ORIGIN |
L'origine pubblica del servizio: l'indirizzo dell'anteprima per il servizio di anteprima, o l'indirizzo della porta del servizio stesso per qualsiasi altro servizio con una porta. Letta dal plugin @kendordev/vite. |
Collega il tuo server a $HOST e $PORT (oppure a 0.0.0.0 e alla porta dichiarata) in modo che
l'anteprima possa raggiungerlo. Il codice del browser che chiama http://localhost:<port> viene
inviato a quella porta nella sandbox; vedi
localhost nell'anteprima.
Riferimenti per le variabili d'ambiente
Un valore in env.vars deve usare una di quattro forme. Qualsiasi altra cosa non supera la validazione.
| Forma | Esempio | Si risolve in |
|---|---|---|
routing.<service>.url |
routing.api.url |
L'URL pubblico di quel servizio: l'indirizzo dell'anteprima più il percorso routing più lungo del servizio. Solo l'indirizzo dell'anteprima quando il percorso del servizio è / o non ha una route. Il servizio deve esistere. |
databases.<type>.url |
databases.postgres.url |
L'URL di connessione di un database dichiarato sotto databases. |
vars.<NAME> |
vars.sessionId |
Un valore fornito da Kendor: assessmentId, challengeId o sessionId. Altri nomi non superano la validazione. |
lit:<text> |
lit:debug |
Il testo dopo lit:, così com'è. |
Anche i database impostano le proprie variabili, come DATABASE_URL e REDIS_URL, per ogni processo
della sandbox. databases.<type>.url ti serve solo quando il tuo codice legge un nome diverso.
preview
| Chiave | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
service |
stringa | Sì, quando preview è presente |
Il servizio il cui dev server viene mostrato nel riquadro di anteprima. Deve esistere. |
preview è obbligatorio quando c'è più di un servizio. Con un solo servizio, quel servizio è
l'anteprima. Un progetto i cui servizi non hanno un comando dev non ha anteprima, solo un terminale.
routing
Una lista di route sull'indirizzo di anteprima della sandbox. Ogni richiesta va alla route con il
prefisso di percorso corrispondente più lungo. Il percorso completo viene inoltrato, quindi un
servizio instradato su /api riceve /api/products, non /products.
| Chiave | Tipo | Obbligatoria | Descrizione |
|---|---|---|---|
path |
stringa | Sì | Inizia con /. Aggiungi una route / come regola generale. |
service |
stringa | Sì | Un servizio esistente. Le route verso un servizio senza dev.port vengono ignorate. |
Con delle route dichiarate, l'anteprima mostra una breve pagina di attesa finché tutti i servizi instradati non accettano connessioni. Vedi App con più servizi.
sandbox
Permette alla sandbox di eseguire i propri strumenti per container.
| Chiave | Tipo | Predefinito | Descrizione |
|---|---|---|---|
containers |
booleano | false |
Un daemon Docker dentro la sandbox, con docker, docker compose e buildx. |
kubernetes |
booleano | false |
Un cluster k3s a nodo singolo avviato al boot, con kubectl e helm. Attiva anche containers. |
Entrambe le opzioni danno alla sandbox più memoria e CPU. L'anteprima può aprire le porte pubblicate da
docker run -p o da Compose, e da kubectl port-forward con --address 0.0.0.0. Una configurazione
con containers o kubernetes non può definire alcun comando test, quindi non c'è nulla da
eseguire dalla scheda Test; usala per le sfide che valuti leggendo il lavoro. La pagina dei prezzi
elenca gli ambienti con container nel piano Enterprise.
version: 1
runtime:
type: node
version: "22"
sandbox:
containers: true
services:
app:
install:
commands:
- npm ci
dev:
command: docker compose uprequests
Richieste HTTP di esempio che compaiono, pronte da inviare, nella scheda Richieste dell'editor. Le
richieste vengono inviate dall'interno della sandbox, quindi localhost funziona come con curl nel
terminale. Non cambiano mai il modo in cui parte la sandbox.
| Chiave | Tipo | Obbligatoria | Predefinito | Descrizione |
|---|---|---|---|---|
name |
stringa | Sì | L'etichetta mostrata nell'elenco. | |
method |
stringa | No | GET |
GET, POST, PUT, PATCH, DELETE, HEAD o OPTIONS. |
url |
stringa | Sì | Un URL completo come http://localhost:3000/api/todos, oppure un percorso come /api/todos, che viene inviato alla porta del servizio di anteprima. |
|
headers |
mappa | No | Dal nome dell'header al valore. | |
body |
stringa | No | Il corpo della richiesta. |
Un esempio con un errore viene escluso dalla scheda; gli altri vengono mostrati comunque.
kendor
Impostazioni riservate a chi crea la sfida. Un candidato non può modificarle. Il blocco accetta chiavi aggiuntive senza errori.
| Chiave | Tipo | Descrizione |
|---|---|---|
gradeService |
stringa | Il servizio il cui test.command viene eseguito dalla scheda Test. Per impostazione predefinita è il servizio di anteprima. Deve indicare un servizio esistente. |
gradeServices |
lista di stringhe | Più servizi i cui comandi di test vengono eseguiti dalla scheda Test, ciascuno nel proprio workDir. I risultati sono elencati come service › test. Ogni servizio indicato deve esistere e avere un test. Usa questa chiave oppure gradeService, non entrambe. |
Il blocco contiene anche chiavi che il catalogo di template di Kendor usa per descrivere i propri
template: title, entryFile, order, type, difficulty, category, tags, editablePaths,
readonlyPaths e solutionDir. Non hanno alcun effetto sulla tua sfida: imposta invece i percorsi
di sola lettura nelle Impostazioni dell'editor della prova (vedi
Come i candidati eseguono i test).
Regole di validazione
Un file viene salvato solo quando valgono tutte queste condizioni:
versionè1, eruntimee almeno un servizio sono presenti.- Nessuna chiave sconosciuta al di fuori di
kendor. - I nomi dei servizi corrispondono a
^[a-z][a-z0-9-]*$e nessuno èkendor-db. - Ogni servizio ha un
devo untest. workDiredatabases[].initsono percorsi relativi dentro il workspace: senza/iniziale, senza lettera di unità, senza...- Due servizi non usano lo stesso
dev.port. preview.serviceindica un servizio esistente, epreviewè presente quando i servizi sono due o più.- Ogni
routing[].serviceindica un servizio esistente, e ognipathinizia con/. - Ogni valore di
env.varsusa una delle quattro forme di riferimento;routing.<service>.urlindica un servizio esistente,databases.<type>.urlindica un database dichiarato, evars.<NAME>èassessmentId,challengeIdosessionId. - Ogni linguaggio compare una sola volta tra
runtimeetoolchains, e ogni tipo di database una sola volta. - Al massimo un database SQL:
postgresomysql, non entrambi. name,user,passwordeinitcompaiono solo su un databasepostgres,mysqlomongodb, enamerispetta la regola di denominazione indicata sopra.kendor.gradeServicee ogni voce dikendor.gradeServicesindicano servizi esistenti, le voci digradeServiceshanno untest, e le due chiavi non sono usate insieme.- Con
sandbox.containersosandbox.kubernetes, nessun servizio ha unteste négradeServicenégradeServicessono impostati. - Ogni versione di linguaggio e di database è una di quelle offerte da Kendor. Le versioni che non sono più offerte per le nuove sfide continuano a passare, così una sfida che ne usa una continua a poter essere salvata.