Referência do build.pl

builder/build.pl é o builder de site estático que o Chinaski executa após mudanças de conteúdo e configurações. Ele lê o conteúdo do banco de dados, renderiza HTML em um diretório de staging, o verifica, e o troca ao vivo apenas quando o build está saudável. Não há flags de linha de comando. O builder é controlado inteiramente por variáveis de ambiente, as configurações que você edita na área de admin e os controles de build no dashboard.

Esta página cobre o ciclo de vida completo do build e as chaves que você pode usar ao executar o builder à mão. (Invocação recomendada para execuções manuais: defina CHINASKI_DB e CHINASKI_OUTPUT primeiro, correspondendo a como o CMS o executa.)

Guardrails

O builder se recusa a executar como root: os arquivos de saída ficariam sem permissão de escrita para o usuário de serviço chinaski. Execute-o como o usuário chinaski (por exemplo sudo -u chinaski perl builder/build.pl).
O builder se recusa a executar de todo se o arquivo de banco de dados não existir.

Onde as coisas vivem

Banco de dados : CHINASKI_DB se definida; caso contrário chinaski.db na raiz do app.
Saída : CHINASKI_OUTPUT se definida; caso contrário output na raiz do repo.
Templates de bloco : CHINASKI_BLOCK_TEMPLATES se definida; caso contrário builder/block_templates no repo.
Um build completo mantém as últimas 100 linhas do build history (visível em Builds na área de admin).

Builds full vs incremental

O build padrão é incremental: ele reutiliza o que já está ao vivo.

Um build incremental só é tentado quando:

o modo incremental foi de fato requisitado,
existe um build bem-sucedido anterior registrado (e não carimbado no futuro),
o diretório de saída ao vivo ainda existe e contém um index.html,
a fingerprint de build armazenada está inalterada (uma divergência de fingerprint significa uma mudança global, como uma troca de tema . Isso dispara um build full),
e o seeding da cópia de staging da árvore ao vivo tem sucesso; se o seed falha, o build inteiro silenciosamente cai para full.

Qualquer outra coisa causa um build full, e o motivo é registrado no build history.

Para forçar um rebuild full limpo: use a caixa Full rebuild no dashboard, defina CHINASKI_FORCE_FULL=1, ou execute bin/force-full-build.pl, que limpa o cache de build e então roda um build full.

Prioridades e paralelismo

CHINASKI_JOBS define quantos workers paralelos renderizam páginas. Deve ser um número puro; prevalece sobre a configuração build_jobs na área de admin, e ambos fazem fallback para a contagem de CPUs. O valor é limitado à faixa 1–16. Um valor de 1 constrói sequencialmente sem processos extras.

O timeout

Cada build tem um limite rígido de wall-clock de 30 minutos (1800 segundos). Quando o limite é atingido, os workers de renderização em voo são mortos e o build morre com uma mensagem de timeout; nada é promovido.

Como um build executa

Checagem de elegibilidade : incremental ou full é decidido antes de qualquer coisa ser escrita, para que uma checagem com falha nunca possa danificar o site ao vivo.
Renderizar para staging : páginas, posts e todo o resto são renderizados em <output>.next, um diretório de staging ao lado da saída ao vivo. Builds incrementais pulam a reescrita de páginas inalteradas reutilizando arquivos do build anterior.
Verificar qualidade : o promotion guard compara este build contra a última promoção saudável (veja abaixo). Erros de renderização são colhidos conforme acontecem.
Escrever o manifest assinado : uma atestação assinada da saída é produzida apenas após todas as checagens passarem, e apenas se nenhum erro já tivesse bloqueado o build. Se a assinatura falha, o build aborta e o manifest anterior é restaurado . A menos que o manifest esteja marcado como opcional.
Promover : o diretório de staging é trocado ao vivo. A troca é atômica (um único rename), então não há janela em que o site está meio atualizado.

Quando um build se recusa a promover

O build nunca promove sobre um resultado quebrado. Três condições o detêm:

Erros de renderização. Qualquer falha de template ou renderização bloqueia a promoção. A saída ao vivo fica intocada, o staging é descartado, e os templates que falharam são reportados.
O promotion guard (modo enforce). O guard compara este build contra a última promoção limpa: queda na contagem de páginas (limiar padrão 80%), aumento de links quebrados (padrão 25) e aumento de problemas de acessibilidade (padrão 10), mais um limite absoluto opcional de blocos não resolvidos. No modo enforce a promoção é bloqueada exatamente como uma falha de renderização. No modo warn (o padrão) o problema é registrado mas o build ainda promove. As configurações do guard ficam em Settings → Workflow.
Falha de manifest. Um build não pode promover sem um manifest assinado utilizável.

Sobrescrever um bloqueio do guard é possível para um build por vez: o controle Promote anyway no dashboard, ou CHINASKI_FORCE_PROMOTE=1. Forçar nunca atualiza as baselines de qualidade . O próximo build normal ainda compara contra a última promoção limpa, para que um build ruim forçado possa ser pego depois.

Códigos de saída

O builder sai com 0 em uma promoção que completou de forma limpa com zero erros de renderização, e 1 em qualquer outra coisa: um bloqueio do guard, erros de renderização, um timeout, uma falha de manifest ou uma promoção com falha. A tooling de deploy depende disso . Uma saída diferente de zero aborta um deploy padrão em vez de reiniciar o serviço sobre saída obsoleta.

Executando builds pela área de admin

Você normalmente não roda o build.pl à mão:

Salvar configurações que afetam a saída, ou mudar o prefixo de URL de posts, despacha um build automaticamente.
O dashboard (via Build) oferece um build normal (incremental), um Full rebuild e um Promote anyway, cada um com sua própria mensagem de confirmação.
Apenas um build executa por vez: iniciar um segundo é recusado com “a build is already in progress”. O lock também expira por si só se um build nunca reportar de volta, para que não possa travar builds permanentemente.
Enquanto um build executa, /admin/build/status reporta o progresso, e o build history mostra os últimos 100 builds completados . Incluindo bloqueados e com erro.
Se um e-mail de notificação de build estiver configurado em Settings → Email, uma mensagem é enviada quando um build tem sucesso ou falha (entregue através do relay SMTP, então precisa de SMTP configurado e é pulado no modo air-gap).

Modo air-gap

Com CHINASKI_AIRGAP=1 definida, o builder remove todas as referências externas das páginas geradas: analytics GA4/GTM são removidos mesmo que configurados, e código de snippet que referencia URLs externas é removido. As páginas construídas então não carregam nada de um CDN.

Referência rápida de ambiente

Variável	Efeito
`CHINASKI_DB`	Banco de dados de onde ler (sobrescreve o padrão)
`CHINASKI_OUTPUT`	Onde publicar
`CHINASKI_INCREMENTAL=1`	Requisita incremental (ainda pode cair para full)
`CHINASKI_FORCE_FULL=1`	Força um rebuild full limpo
`CHINASKI_FORCE_PROMOTE=1`	Contorna o promotion guard para este build
`CHINASKI_JOBS`	Contagem de workers paralelos (1–16)
`CHINASKI_BLOCK_TEMPLATES`	Diretório de templates de bloco
`CHINASKI_MANIFEST_OPTIONAL=1`	Rebaixa falha de manifest assinado para um aviso
`CHINASKI_AIRGAP`	Remove analytics e referências externas de snippets
`CHINASKI_TEST`	Válvula de escape de modo teste (permite executar como root)

Veja a referência de variáveis de ambiente para o contexto das variáveis compartilhadas.