Runtimes

A Zenifra não faz detecção automática de runtime. Em projetos com origem em um repositório Git, o usuário escolhe explicitamente o runtime no momento da criação do projeto.

Runtimes suportados

Nota: Hoje, os runtimes oficialmente suportados para builds por repositório Git são Node.js, Python e Bun. Java, Go, PHP, .NET, Nginx, Apache e outros stacks devem ser publicados via Imagem OCI.

Versões disponíveis

Escolha a mesma versão principal usada no desenvolvimento. A porta sugerida é apenas um ponto de partida: o campo Porta do projeto precisa ser igual à porta em que a aplicação escuta.

Ambiente de build e execução

• As variáveis de ambiente do projeto ficam disponíveis durante a instalação de dependências, o pre-build e a build, além da execução. Isso permite usar variáveis em etapas de build, como NEXT_PUBLIC_* ou VITE_*.
• Alterar uma variável reinicia as instâncias, mas não refaz a build. Valores embutidos durante a build só mudam numa nova publicação.
• A aplicação roda com um usuário sem privilégios, dentro do diretório da aplicação. Ela pode gravar nesse diretório, mas os arquivos são efêmeros, salvo no armazenamento persistente.
• No Node.js e no Bun, a execução usa NODE_ENV=production.
• A build usa a pasta definida em Diretório raiz (por padrão, a raiz do repositório; em monorepos, uma subpasta como backend) e um ambiente gerado pela Zenifra para o runtime escolhido: um Dockerfile existente no repositório não é usado. Para construir com o seu próprio Dockerfile, publique uma Imagem OCI.
• A pasta .git do repositório não é incluída na aplicação publicada. Se sua aplicação lia informações do Git em tempo de execução (por exemplo, o commit atual), use uma variável de ambiente.
• No Python, a saída de print() e logging é enviada sem buffer para os logs, e o ambiente de build inclui compilador C e as bibliotecas do cliente PostgreSQL para pacotes com extensões nativas.

Regra importante

Em projetos GitHub criados pelo console, runtime, versão e branch não podem ser alterados no console; pela API (PUT /v1/project/:id/source) ou pela CLI (zenifra project source) é possível reconfigurar a origem. Em projetos Forgejo, a seção Repositório Git da página do projeto permite alterar runtime (Node.js ou Python), versão e comandos; a API também aceita Bun.

Node.js

Arquivos obrigatórios

{
  "name": "my-app",
  "scripts": {
    "start": "node index.js"
  }
}

Para projetos Node.js baseados em Git, estes arquivos são obrigatórios:

• package.json
• package-lock.json

Instalação padrão de dependências

A Zenifra instala as dependências com:

npm ci

Por padrão, npm ci instala as dependências declaradas no lockfile. Mantenha TypeScript, bundlers e outras ferramentas de build em devDependencies. Se a configuração do projeto definir NODE_ENV=production para a build, essa instalação omite essas dependências; nesse caso, configure o pre-build como npm install --include=dev. Ele é executado depois da instalação padrão e antes de npm run build, tornando as ferramentas disponíveis para a build.

Depois da build: assim como no Heroku, as devDependencies são removidas antes de publicar a aplicação, com ou sem comando build. Tudo o que o comando start usa precisa estar em dependencies. Para mantê-las, defina NPM_CONFIG_PRODUCTION=false; veja devDependencies depois da build.

Projetos Git com Yarn ou pnpm só são compatíveis com o runtime Node.js atual quando também fornecem um package-lock.json npm compatível. A Zenifra não converte automaticamente lockfiles nem workspaces de Yarn ou pnpm; sem um lockfile npm compatível, publique uma Imagem OCI preparada pelo seu próprio processo de build.

Comandos do projeto

Depois da instalação padrão, os comandos abaixo são definidos pelo usuário na criação do projeto:

• pre-build (opcional)
• build (opcional)
• start (obrigatório)

Um uso comum de pre-build em Node.js é gerar código antes da build, como clientes de ORM. O pre-build roda durante a build, não a cada início da aplicação; para migrations de banco, prefira executá-las no início do start, como mostram os guias por framework.

Python

Arquivos de dependências

Mantenha um requirements.txt no Diretório raiz do projeto (por padrão, a raiz do repositório) com as dependências de execução. A instalação abaixo só roda quando esse arquivo existe. Se o repositório também tiver pyproject.toml ou setup.py, o pacote é instalado com pip install -e . depois da build.

Instalação padrão de dependências

pip install --no-cache-dir -r requirements.txt

Comandos do projeto

Assim como em Node.js, estes comandos são definidos pelo usuário na criação do projeto:

• pre-build (opcional)
• build (opcional)
• start (obrigatório)

Bun

Arquivos

{
  "name": "my-app",
  "scripts": {
    "start": "bun index.ts"
  }
}

• package.json (obrigatório)
• bun.lock (recomendado): versione o lockfile para que a build instale exatamente as mesmas versões usadas no desenvolvimento. Gere-o com a mesma versão do Bun escolhida no projeto: um lockfile criado por uma versão mais nova pode ser recusado por uma versão anterior.

Instalação padrão de dependências

bun install --frozen-lockfile

As devDependencies continuam instaladas depois da build, então ferramentas como TypeScript e bundlers ficam disponíveis no pre-build e na build. O Bun executa TypeScript diretamente, sem etapa de compilação obrigatória.

Comandos do projeto

O comando start padrão é bun run start, que executa o script start do package.json. Assim como nos outros runtimes, também é possível definir:

• pre-build (opcional)
• build (opcional)
• start (obrigatório)

O que editar depois

Em projetos GitHub, depois da criação, ficam editáveis os comandos pre-build, build e start e a forma de atualização; runtime, versão e branch são definidos na criação. Consulte Implantação via GitHub.

Em projetos Forgejo, também é possível trocar repositório, branch, runtime, versão e modo de deploy depois da criação; consulte Deploy a partir do Forgejo.