Saltar para o conteúdo
KendorDocs

Referência do kendor.yaml

Para autores de desafios ·

Todas as chaves que o kendor.yaml aceita, de runtime e services a routing, databases e sandbox, com tipos, valores por omissão e as regras verificadas ao guardar.

O kendor.yaml fica na raiz do projeto de um desafio e diz à sandbox o que executar: uma linguagem e versão, linguagens e bases de dados extra opcionais, e um ou mais serviços com os respetivos comandos de instalação, dev e teste. Só version, runtime e services são obrigatórios. O Kendor verifica o ficheiro inteiro quando guardas, e um ficheiro com erros não é guardado.

Onde está o ficheiro e quando se aplica

O ficheiro é kendor.yaml, na raiz do workspace. Num zip carregado ou num repositório importado, o Kendor aceita também a grafia kendor.yml.

No editor do desafio, abre Definições e escolhe Configurar runtime…. A janela Configuração do runtime tem um separador Formulário e um separador YAML em bruto; ao guardar, escreve o kendor.yaml e reinicia a pré-visualização. Se editares o ficheiro à mão, aparece um aviso kendor.yaml alterado, porque a sandbox continua a correr a configuração anterior até escolheres Guardar e reiniciar.

Ao guardar, o Kendor executa as verificações listadas em Regras de validação e verifica também se cada versão de linguagem e de base de dados é uma que o Kendor oferece. Cada problema é indicado com o seu caminho no ficheiro, por exemplo services.web.dev.port.

A cópia do kendor.yaml dentro de uma sandbox em execução é regenerada a partir da configuração guardada sempre que a sandbox arranca, por isso mostra sempre o que a sandbox está a executar.

Dica. Começa o ficheiro com # yaml-language-server: $schema=https://kendor.dev/config-schema/v1. Os editores que usam o servidor de linguagem YAML passam então a oferecer autocompletar e erros em linha para todas as chaves desta página.

O que os candidatos podem alterar

Um candidato pode editar o kendor.yaml no seu próprio workspace. Só quatro chaves de topo são lidas da cópia dele: install, services, preview e routing. As alterações aplicam-se quando a sandbox reinicia, e só se o ficheiro resultante da junção continuar a passar na validação; caso contrário, a tua configuração mantém-se. runtime, toolchains, databases, sandbox e kendor vêm sempre do teu ficheiro, e o mesmo acontece com os comandos de teste: qualquer test que um candidato escreva é descartado, e os teus comandos test são mantidos nos serviços que definiste.

Um exemplo completo

Uma API Node.js e um frontend Vite, com PostgreSQL e Valkey, mais um worker em 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

Chaves de topo

As chaves desconhecidas são rejeitadas em todo o ficheiro, exceto dentro de kendor.

Chave Tipo Obrigatória Descrição
version número Sim O formato do ficheiro. Tem de ser 1.
runtime mapeamento Sim A linguagem principal e a sua versão.
toolchains lista Não Linguagens extra na mesma sandbox.
databases lista Não Servidores PostgreSQL, MySQL, MongoDB e Valkey dentro da sandbox.
install mapeamento Não Comandos executados uma vez na raiz do workspace antes de qualquer serviço.
services mapeamento Sim Os processos a instalar, iniciar e testar, indexados por nome. Pelo menos um.
preview mapeamento Quando há 2 ou mais serviços Que serviço o painel de pré-visualização mostra.
routing lista Não Prefixos de caminho no endereço da pré-visualização e o serviço para onde cada um vai.
sandbox mapeamento Não Docker ou Kubernetes dentro da sandbox.
requests lista Não Pedidos HTTP de exemplo para o separador Pedidos do editor.
kendor mapeamento Não Definições só para autores.

Nota. Escreve as versões como texto entre aspas: version: "3.12", não version: 3.12. Sem aspas, o YAML lê 3.12 como um número e o ficheiro falha a validação. O version: 1 de topo é a exceção; tem de ser o número 1.

runtime

Chave Tipo Obrigatória Por omissão Descrição
type texto Sim Um de node, php, python, go, java, rust, cpp.
version texto Sim Uma versão que o Kendor ofereça para essa linguagem, como "22" ou "1.27". Vê Linguagens e versões.
packageManager texto Não Não definido npm, pnpm, yarn ou bun. Fica registado como referência; o que realmente instala são os teus comandos install.

A linguagem de um desafio fica fixa quando ele é criado, mas a versão não: quando runtime.type é a linguagem do desafio, runtime.version decide que versão a sandbox executa.

toolchains

Uma lista de linguagens extra, cada uma com o seu compilador, ferramentas e servidor de linguagem no PATH ao lado da principal. Usa-a para um serviço Go ao lado de uma app Node, ou para Node nas compilações de assets num projeto PHP.

Chave Tipo Obrigatória Descrição
type texto Sim As mesmas opções de runtime.type.
version texto Sim Uma versão que o Kendor ofereça para essa linguagem.

Cada linguagem pode aparecer uma só vez entre runtime e toolchains.

databases

Uma lista de servidores de bases de dados que correm dentro da sandbox em 127.0.0.1 e arrancam antes de qualquer comando de instalação. Vê Bases de dados na sandbox para os detalhes de ligação.

Chave Tipo Obrigatória Por omissão Descrição
type texto Sim postgres, mysql, mongodb ou valkey. Cada tipo no máximo uma vez, e não postgres e mysql ao mesmo tempo.
version texto Sim "18" para o PostgreSQL, "8.4" para o MySQL, "8.0" para o MongoDB, "9" para o Valkey.
name texto Não app PostgreSQL, MySQL e MongoDB. A base de dados a criar: letras minúsculas, dígitos, sublinhados e hífenes, começando por uma letra ou sublinhado, no máximo 63 caracteres, e que não seja postgres, template0, template1, admin, local, config, mysql, information_schema, performance_schema nem sys.
user texto Não kendor PostgreSQL, MySQL e MongoDB. O utilizador com que a app se liga, quando o projeto espera o seu próprio (postgres://shop:secret@localhost/shop). Letras, dígitos, sublinhados e hífenes, no máximo 32. Todas as variáveis de ligação o usam.
password texto Não Não definido (MongoDB: kendor) PostgreSQL, MySQL e MongoDB. A palavra-passe desse utilizador, uma linha com no máximo 128 caracteres. O Kendor preenche user, password e name a partir do .env.example ou do docker-compose de um repositório quando o importas.
init texto Não Não definido PostgreSQL, MySQL e MongoDB. Um ficheiro de seed, ou uma pasta cujos ficheiros de seed correm por ordem de nome, relativo à raiz do workspace: .sql para o PostgreSQL e o MySQL, .js para o MongoDB. Corre uma vez, depois de a base de dados ser criada.

install

Comandos que correm uma vez na raiz do workspace, antes de qualquer serviço arrancar. Usa-o para uma única instalação que cubra o repositório inteiro, como pnpm install num monorepo.

Chave Tipo Obrigatória Descrição
commands lista de textos Sim Pelo menos um. Correm por ordem; se um terminar com código diferente de zero, os comandos a seguir são ignorados.

As bases de dados já estão a correr quando estes comandos começam. Põe as migrações nos comandos migrate de um serviço e não aqui: os comandos de instalação são ignorados num reinício quando nenhum ficheiro de dependências mudou, por isso os novos ficheiros de migração não seriam aplicados.

services

Um mapeamento de nome de serviço para serviço. Os nomes começam por uma letra minúscula e contêm apenas letras minúsculas, dígitos e hífenes, por exemplo api ou web-app. O nome kendor-db está reservado. Cada serviço corre na sua própria janela de processo dentro da sandbox.

Chave Tipo Obrigatória Por omissão Descrição
workDir texto Não . Pasta onde correm os comandos de instalação, dev e teste do serviço, relativa à raiz do workspace. Sem / inicial e sem ...
install mapeamento Não commands: uma lista de pelo menos um comando, executados por ordem em workDir depois do install de topo. Se um falhar, o comando dev do serviço não arranca.
migrate mapeamento Não commands: uma lista de pelo menos um comando que atualiza a base de dados, como npx prisma migrate deploy ou php artisan migrate --force. Correm em workDir sempre que o serviço arranca, depois da instalação e antes do dev, com o ambiente do serviço. Se um falhar, o erro aparece no processo do serviço e o dev arranca na mesma.
dev mapeamento Não O processo de longa duração. Vê abaixo.
test mapeamento Não command: o comando que o separador Testes executa. timeout: segundos que pode demorar antes de ser parado, de 10 a 1800 (por omissão: 10 minutos). Aumenta-o para suites grandes, como uma base de dados de teste que demora a preparar.
publicEnvPrefix texto Não O prefixo das variáveis que é seguro expor ao código do browser, como VITE_. Aceite e guardado; a sandbox não atua sobre ele.

Todos os serviços precisam de pelo menos um dev ou um test. Um serviço só com test (e sem install) não tem janela de processo: é assim que se configuram os desafios de ficheiro único.

Quando um serviço reinicia, a instalação é ignorada se os ficheiros de dependências em workDir (package.json, lockfiles, composer.json, requirements.txt, pyproject.toml, go.mod e semelhantes) não tiverem mudado.

dev

Chave Tipo Obrigatória Descrição
command texto Sim O comando que inicia o serviço, por exemplo npm run dev -- --port $PORT.
port inteiro Não De 1 a 65535. A porta em que o serviço escuta. Dois serviços não podem partilhar uma porta.
env.vars mapeamento Não Variáveis de ambiente para este comando. Os nomes seguem [A-Za-z_][A-Za-z0-9_]*; os valores são referências, descritas abaixo.

O Kendor define estas variáveis para todos os comandos dev, e elas sobrepõem-se a qualquer coisa em env.vars:

Variável Valor
HOST 0.0.0.0
PORT A port do serviço, quando tem uma.
KENDOR_PUBLIC_HOST O nome de anfitrião público da pré-visualização da sandbox.
KENDOR_VITE_ORIGIN A origem pública do serviço: o endereço da pré-visualização para o serviço de pré-visualização, ou o endereço da porta do próprio serviço para qualquer outro serviço com porta. Lida pelo plugin @kendordev/vite.

Liga o teu servidor a $HOST e $PORT (ou a 0.0.0.0 e à porta declarada) para que a pré-visualização o consiga alcançar. O código do browser que chama http://localhost:<port> é enviado para essa porta na sandbox; vê localhost na pré-visualização.

Referências a variáveis de ambiente

Um valor em env.vars tem de usar uma de quatro formas. Qualquer outra falha a validação.

Forma Exemplo Resolve para
routing.<service>.url routing.api.url O URL público desse serviço: o endereço da pré-visualização mais o caminho routing mais longo do serviço. Apenas o endereço da pré-visualização quando o caminho do serviço é / ou ele não tem rota. O serviço tem de existir.
databases.<type>.url databases.postgres.url O URL de ligação de uma base de dados declarada em databases.
vars.<NAME> vars.sessionId Um valor que o Kendor fornece: assessmentId, challengeId ou sessionId. Outros nomes falham a validação.
lit:<text> lit:debug O texto depois de lit:, tal como está.

As bases de dados também definem as suas próprias variáveis, como DATABASE_URL e REDIS_URL, para todos os processos da sandbox. Só precisas de databases.<type>.url quando o teu código lê outro nome.

preview

Chave Tipo Obrigatória Descrição
service texto Sim, quando preview está presente O serviço cujo servidor dev o painel de pré-visualização mostra. Tem de existir.

preview é obrigatório quando há mais do que um serviço. Com um só serviço, esse serviço é a pré-visualização. Um projeto cujos serviços não têm comando dev não tem pré-visualização, apenas um terminal.

routing

Uma lista de rotas no endereço de pré-visualização da sandbox. Cada pedido vai para a rota com o prefixo de caminho correspondente mais longo. O caminho completo é passado, por isso um serviço encaminhado em /api recebe /api/products, não /products.

Chave Tipo Obrigatória Descrição
path texto Sim Começa por /. Adiciona uma rota / como captura geral.
service texto Sim Um serviço existente. As rotas para um serviço sem dev.port são ignoradas.

Com rotas declaradas, a pré-visualização mostra uma breve página de espera até todos os serviços encaminhados estarem a aceitar ligações. Vê Apps com vários serviços.

sandbox

Permite que a sandbox execute as suas próprias ferramentas de contentores.

Chave Tipo Por omissão Descrição
containers booleano false Um daemon Docker dentro da sandbox, com docker, docker compose e buildx.
kubernetes booleano false Um cluster k3s de um só nó iniciado no arranque, com kubectl e helm. Ativa também containers.

Qualquer uma das duas dá mais memória e CPU à sandbox. A pré-visualização pode abrir portas publicadas por docker run -p ou pelo Compose, e kubectl port-forward com --address 0.0.0.0. Uma configuração com containers ou kubernetes não pode definir nenhum comando test, por isso não há nada para executar a partir do separador Testes; usa-a em desafios que revês lendo o trabalho. A página de preços lista os ambientes de contentores no plano 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

Pedidos HTTP de exemplo que aparecem, prontos a enviar, no separador Pedidos do editor. Os pedidos são enviados de dentro da sandbox, por isso o localhost funciona como com curl no terminal. Nunca alteram a forma como a sandbox arranca.

Chave Tipo Obrigatória Por omissão Descrição
name texto Sim A etiqueta mostrada na lista.
method texto Não GET GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS.
url texto Sim Um URL completo como http://localhost:3000/api/todos, ou um caminho como /api/todos, que é enviado para a porta do serviço de pré-visualização.
headers mapeamento Não Nome do cabeçalho para valor.
body texto Não O corpo do pedido.

Um exemplo com um erro fica de fora do separador; os restantes continuam a aparecer.

kendor

Definições só para autores. Um candidato não as pode alterar. O bloco aceita chaves extra sem erro.

Chave Tipo Descrição
gradeService texto O serviço cujo test.command o separador Testes executa. Por omissão, o serviço de pré-visualização. Tem de indicar um serviço existente.
gradeServices lista de textos Vários serviços cujos comandos de teste o separador Testes executa, cada um no seu próprio workDir. Os resultados aparecem como service › test. Todos os serviços indicados têm de existir e ter um test. Usa esta chave ou gradeService, não as duas.

O bloco contém também chaves que o catálogo de templates do próprio Kendor usa para descrever os seus templates: title, entryFile, order, type, difficulty, category, tags, editablePaths, readonlyPaths e solutionDir. Não têm qualquer efeito no teu desafio: define os caminhos só de leitura em Definições do editor da triagem (vê Como os candidatos executam testes).

Regras de validação

Um ficheiro só é guardado quando todas estas condições se verificam:

  • version é 1, e runtime e pelo menos um serviço estão presentes.
  • Não há chaves desconhecidas fora de kendor.
  • Os nomes de serviço seguem ^[a-z][a-z0-9-]*$ e nenhum é kendor-db.
  • Todos os serviços têm um dev ou um test.
  • workDir e databases[].init são caminhos relativos dentro do workspace: sem / inicial, sem letra de unidade, sem ...
  • Dois serviços não usam o mesmo dev.port.
  • preview.service indica um serviço existente, e preview está presente quando há dois ou mais serviços.
  • Todos os routing[].service indicam um serviço existente, e todos os path começam por /.
  • Todos os valores de env.vars usam uma das quatro formas de referência; routing.<service>.url indica um serviço existente, databases.<type>.url indica uma base de dados declarada, e vars.<NAME> é assessmentId, challengeId ou sessionId.
  • Cada linguagem aparece uma só vez entre runtime e toolchains, e cada tipo de base de dados uma só vez.
  • No máximo uma base de dados SQL: postgres ou mysql, não ambas.
  • name, user, password e init aparecem apenas numa base de dados postgres, mysql ou mongodb, e name segue a regra de nomes acima.
  • kendor.gradeService e todas as entradas de kendor.gradeServices indicam serviços existentes, as entradas de gradeServices têm um test, e as duas chaves não são usadas em conjunto.
  • Com sandbox.containers ou sandbox.kubernetes, nenhum serviço tem um test e nem gradeService nem gradeServices estão definidos.
  • Todas as versões de linguagem e de base de dados são versões que o Kendor oferece. As versões que já não são oferecidas para novos desafios continuam a passar, para que um desafio que use uma continue a guardar.
Este artigo foi útil?