RuntimesCopy Anchor Link

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 suportadosCopy Anchor Link

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

Versões disponíveisCopy Anchor Link

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çãoCopy Anchor Link

• 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 importanteCopy Anchor Link

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, versão e comandos.

Node.jsCopy Anchor Link

Arquivos obrigatóriosCopy Anchor Link

{
  "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ênciasCopy Anchor Link

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. O runtime atual não remove devDependencies depois dessa etapa.

Sem comando build: quando o campo build fica vazio, as devDependencies são removidas depois da instalação. Tudo o que o comando start usa precisa estar em dependencies.

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 projetoCopy Anchor Link

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.

PythonCopy Anchor Link

Arquivos de dependênciasCopy Anchor Link

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ênciasCopy Anchor Link

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

Comandos do projetoCopy Anchor Link

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)

BunCopy Anchor Link

ArquivosCopy Anchor Link

{
  "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ênciasCopy Anchor Link

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 projetoCopy Anchor Link

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)

GoCopy Anchor Link

ArquivosCopy Anchor Link

Mantenha o go.mod (e o go.sum) no Diretório raiz do projeto (por padrão, a raiz do repositório). Escolha uma versão do Go igual ou mais nova que a linha go do go.mod: com uma versão anterior, a build para com go.mod requires go >= …. Não há etapa de instalação separada: os módulos são baixados pela própria build, e uma pasta vendor/ versionada funciona com go build -mod=vendor.

Comandos padrãoCopy Anchor Link

# build
go build -o app .

# start
./app

A build padrão compila o pacote main da raiz. Se ele estiver numa subpasta, como no formato cmd/server, aponte a build para ela:

go build -o app ./cmd/server

O pre-build (opcional, por exemplo go generate ./...) roda antes da build. Se o campo build ficar vazio, nada é compilado e o start não terá o que executar.

ObservaçõesCopy Anchor Link

• A build é estática: o CGO fica desativado e o ambiente não tem compilador C. Pacotes que dependem de CGO precisam de uma alternativa em Go puro ou de uma Imagem OCI. Por exemplo, github.com/mattn/go-sqlite3 compila, mas falha quando a aplicação inicia (requires cgo); use modernc.org/sqlite. Drivers em Go puro, como o pgx, funcionam normalmente.
• Arquivos incorporados com //go:embed (templates, arquivos estáticos) entram no binário normalmente.
• O binário não inclui informações do Git. Para expor a versão ou o commit, use uma variável de ambiente.
• O ambiente define PORT=8080 por padrão. Leia a porta de PORT e mantenha o campo Porta do projeto igual à porta em que a aplicação escuta.

JavaCopy Anchor Link

Ambiente e arquivosCopy Anchor Link

A build usa um JDK Eclipse Temurin na versão escolhida (17, 21 ou 25) com Maven 3.9. Em projetos Maven, mantenha o pom.xml no Diretório raiz; em projetos Gradle, versione o wrapper (gradlew e a pasta gradle/). Não há etapa de instalação separada: as dependências são baixadas pela build. Se o projeto tiver um .dockerignore, ele não é usado nessa build.

Comandos padrão (Maven)Copy Anchor Link

# build
mvn -B -DskipTests package

# start
java -jar target/*.jar

O start padrão espera um único jar executável em target/, como o gerado pelo Spring Boot. Se o projeto tiver o Maven Wrapper, use ./mvnw -B -DskipTests package como build.

GradleCopy Anchor Link

Projetos Gradle usam o wrapper do próprio repositório. Por exemplo, com Spring Boot:

# build
./gradlew bootJar -x test

# start
java -jar build/libs/<nome>.jar

• Aponte o jar exato no start: o Gradle também gera um -plain.jar, que não é executável.
• Se o build.gradle define um toolchain Java (languageVersion = JavaLanguageVersion.of(17)), escolha essa mesma versão no projeto. Caso contrário, a build falha procurando esse JDK.
• Com Kotlin e Ktor, ./gradlew buildFatJar gera build/libs/<nome>-all.jar.

Outros frameworksCopy Anchor Link

No Quarkus, defina quarkus.http.port=${PORT:8080} no application.properties ou mantenha a Porta do projeto em 8080.

Um programa de arquivo único (Main.java) pode rodar sem build: deixe o build vazio e use java Main.java como start.

MemóriaCopy Anchor Link

A aplicação inicia com -XX:MaxRAMPercentage=75: a JVM usa até 75% da memória do plano para o heap, em vez dos 25% padrão da JVM. Para mudar, defina a variável de ambiente JAVA_TOOL_OPTIONS.

ObservaçõesCopy Anchor Link

• O pre-build (opcional) roda antes da build.
• O ambiente define PORT=8080 por padrão, e o Spring Boot já escuta em 8080. Se a aplicação usar outra porta, ajuste o campo Porta do projeto.

O que editar depoisCopy Anchor Link

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.