Variáveis de ambiente

Variáveis de ambiente guardam configuração e segredos fora do código: URLs de banco, chaves de APIs externas, flags de comportamento e qualquer valor que mude entre ambientes. A aplicação lê esses valores em tempo de execução, por exemplo com process.env.DATABASE_URL no Node.js ou os.environ["DATABASE_URL"] no Python.

Onde configurar

Para apenas visualizar valores, use project.env.read. Valores podem ser sensíveis: conceda leitura somente a quem realmente precisa.

Limites

Arquivos grandes, certificados extensos ou listas volumosas não devem ser guardados em variáveis. Prefira gerar esses dados no build, guardá-los no armazenamento persistente ou buscá-los de um serviço próprio.

O que acontece ao alterar

• Salvar alterações em variáveis reinicia as instâncias do projeto para que os novos valores sejam carregados.
• Em projetos com mais de uma instância, planeje a alteração para um horário de menor uso e acompanhe os logs logo após salvar.
• Ambientes de preview herdam as variáveis do projeto principal a cada criação ou atualização do preview. Revise variáveis que apontam para bancos ou serviços compartilhados; veja Ambientes de Preview.

Variáveis definidas pela plataforma

A Zenifra injeta automaticamente:

Use essa variável para identificar a versão em logs, respostas de diagnóstico ou ferramentas de monitoramento. Não defina ZENIFRA_INSTANCE_VERSION manualmente: o valor é sempre substituído pela plataforma.

Conexão com bancos e serviços gerenciados

A DATABASE_URL não é injetada automaticamente em projetos HTTP. Copie os dados de conexão do banco ou do serviço gerenciado no console e cadastre a variável no projeto da aplicação:

DATABASE_URL=postgres://app:SENHA@HOST:PORTA/app
VALKEY_URL=valkeys://default:SENHA@HOST:PORTA/0

Ao rotacionar a senha de um banco, atualize as variáveis de todas as aplicações que o utilizam.

Boas práticas

• Nunca versione segredos no repositório nem os inclua em imagens OCI.
• Use nomes descritivos e em maiúsculas, como STRIPE_WEBHOOK_SECRET ou FEATURE_NEW_CHECKOUT.
• Separe valores de desenvolvimento local (arquivo .env fora do Git) dos valores de produção cadastrados no console.
• Revise quem tem project.env.read: essa permissão permite ler segredos em texto claro.
• Ao suspeitar de vazamento, gere uma nova credencial no serviço de origem, atualize a variável e revogue a antiga.

Próximos passos

• Configuração do projeto
• Armazenamento persistente
• Segurança
• Limites e quotas

FAQ

Preciso fazer um novo deploy depois de alterar uma variável?

Não. Ao salvar, as instâncias são reiniciadas e passam a ler os novos valores.

Posso definir a porta por variável?

A porta da aplicação é configurada no próprio projeto. Se o seu código lê PORT, cadastre a variável com o mesmo valor configurado na porta do projeto.

As variáveis aparecem nos logs?

Não, a menos que a sua aplicação as imprima. Evite registrar valores de segredos.