Vai al contenuto
KendorDocs

Riferimento di kendor.yaml

Per chi crea le sfide ·

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:

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

Chiavi 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.

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

requests

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, e runtime e 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 dev o un test.
  • workDir e databases[].init sono percorsi relativi dentro il workspace: senza / iniziale, senza lettera di unità, senza ...
  • Due servizi non usano lo stesso dev.port.
  • preview.service indica un servizio esistente, e preview è presente quando i servizi sono due o più.
  • Ogni routing[].service indica un servizio esistente, e ogni path inizia con /.
  • Ogni valore di env.vars usa una delle quattro forme di riferimento; routing.<service>.url indica un servizio esistente, databases.<type>.url indica un database dichiarato, e vars.<NAME> è assessmentId, challengeId o sessionId.
  • Ogni linguaggio compare una sola volta tra runtime e toolchains, e ogni tipo di database una sola volta.
  • Al massimo un database SQL: postgres o mysql, non entrambi.
  • name, user, password e init compaiono solo su un database postgres, mysql o mongodb, e name rispetta la regola di denominazione indicata sopra.
  • kendor.gradeService e ogni voce di kendor.gradeServices indicano servizi esistenti, le voci di gradeServices hanno un test, e le due chiavi non sono usate insieme.
  • Con sandbox.containers o sandbox.kubernetes, nessun servizio ha un test e né gradeService né gradeServices sono 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.
Questo articolo ti è stato utile?