Referência do kendor.yaml
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:
# 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: apiChaves 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.
version: 1
runtime:
type: node
version: "22"
sandbox:
containers: true
services:
app:
install:
commands:
- npm ci
dev:
command: docker compose uprequests
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, eruntimee 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
devou umtest. workDiredatabases[].initsão caminhos relativos dentro do workspace: sem/inicial, sem letra de unidade, sem...- Dois serviços não usam o mesmo
dev.port. preview.serviceindica um serviço existente, epreviewestá presente quando há dois ou mais serviços.- Todos os
routing[].serviceindicam um serviço existente, e todos ospathcomeçam por/. - Todos os valores de
env.varsusam uma das quatro formas de referência;routing.<service>.urlindica um serviço existente,databases.<type>.urlindica uma base de dados declarada, evars.<NAME>éassessmentId,challengeIdousessionId. - Cada linguagem aparece uma só vez entre
runtimeetoolchains, e cada tipo de base de dados uma só vez. - No máximo uma base de dados SQL:
postgresoumysql, não ambas. name,user,passwordeinitaparecem apenas numa base de dadospostgres,mysqloumongodb, enamesegue a regra de nomes acima.kendor.gradeServicee todas as entradas dekendor.gradeServicesindicam serviços existentes, as entradas degradeServicestêm umtest, e as duas chaves não são usadas em conjunto.- Com
sandbox.containersousandbox.kubernetes, nenhum serviço tem umteste nemgradeServicenemgradeServicesestã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.