Variáveis de ambiente no Coolify: passo a passo

Resposta rápida

Para criar uma variável de ambiente no Coolify, abra a aplicação, entre em Environment Variables, clique em Add, preencha Name e Value e clique em Add Variable. Escolha se ela vale no build (Build time), na aplicação rodando (Runtime) ou nos dois. A Developer View edita tudo em bloco, no formato NOME=valor. Depois, clique em Redeploy: o valor novo só chega no próximo deploy.

O painel do Coolify é em inglês. Neste manual, os botões aparecem como estão na tela, em negrito, com a tradução ao lado. Dúvida com algum termo? Veja o glossário do Coolify em português.

Você vai aprender

Criar uma variável e escolher se ela vale no build, na execução ou nos dois
Editar várias variáveis de uma vez na Developer View
Reaproveitar valores com as variáveis compartilhadas
Guardar senhas e chaves fora do repositório e esconder o valor no painel

Antes de começar

Uma aplicação criada no Coolify (deploy pelo Git)

Neste guia

Para que servem as variáveis
Crie uma variável
Edite em bloco na Developer View
Use variáveis compartilhadas
As variáveis que o Coolify cria
Aplique com Redeploy
Guarde segredos com segurança
Problemas comuns

Para que servem as variáveis

Variável de ambiente é um valor que a aplicação lê fora do código: o endereço do banco, a chave de uma API, o fuso horário. O mesmo código roda em production e em staging com valores diferentes, e nenhuma senha vai para o repositório.

Build timeO valor existe enquanto a imagem é montada, para o que entra na imagem.
RuntimeO valor existe no contêiner rodando. É o caso mais comum.
SegredoSenha e chave ficam só no Coolify, nunca no repositório.

Crie uma variável

Abra Environment Variables e clique em Add
No painel: site-da-lojaEnvironment Variables(a sua aplicação › Variáveis de ambiente)
Na página da aplicação, abra Environment Variables (variáveis de ambiente). Clique em Add (adicionar) para criar uma variável.
1. Add: abre a janela de variável nova.
2. Developer View: edita todas as variáveis num texto só.
Preencha e clique em Add Variable
No exemplo, TZ=America/Sao_Paulo coloca a aplicação no fuso de Brasília. Comment (comentário) é opcional e serve de lembrete.
1. Name: O nome da variável, como TZ. Por convenção, letras maiúsculas e _.
2. Value: O valor (America/Sao_Paulo). Digite {{ para usar uma variável compartilhada.
3. Build time: Available during build (disponível no build), o padrão, ou Not available during build.
4. Runtime: Available in the container (disponível no contêiner), o padrão, ou Not available in the container.
5. Add Variable: Cria a variável. Ela só chega à aplicação no próximo deploy.
Confira a variável na lista
A variável aparece em Production, com as colunas Buildtime e Runtime marcadas. Ela aparece também em Preview deployments, a seção das prévias de pull request, onde pode ter outro valor.
Dica A engrenagem da coluna Actions abre a variável para editar, travar (Lock) ou apagar (Delete).

Quer entender Value type e Interpolation?

Value type define o formato: Single line (uma linha), o padrão, ou Multiline (várias linhas), para certificados e chaves que ocupam mais de uma linha.

Interpolation trata o caractere $. Em Interpolate $VARIABLES, o padrão, $NOME vira o valor de outra variável. Em Literal (keep $ characters as-is), o $ fica como está: use em senhas com $.

Edite em bloco na Developer View

Edite as variáveis no formato NOME=valor
Clique em Developer View. As variáveis viram um texto, uma por linha, como num arquivo .env. Edite as linhas e salve com Save changes (salvar alterações).
1. A caixa de texto de Production, com uma variável por linha.
2. Save changes, na barra que aparece embaixo enquanto há alteração não salva.
Dica Para voltar à lista, clique em Normal View.

TZ=America/Sao_Paulo
APP_URL=https://loja.example.com
LOJA_MOEDA=BRL
# coolify: literal buildtime=false
CHAVE_DO_PAGAMENTO=CHAVE-DE-EXEMPLO

A linha # coolify: logo acima de uma variável ajusta as opções dela: aqui, Literal e fora do build.

Comentário no fim da linha é descartado

Na Developer View, um comentário depois do valor, com espaço antes do # (NOME=valor #comentário), some ao salvar.

Use variáveis compartilhadas

Quando vários recursos usam o mesmo valor, crie uma variável compartilhada na página Shared Variables (variáveis compartilhadas) e faça referência a ela. Muda num lugar, vale em todos.

Shared Variables do Coolify: variáveis compartilhadas por toda a equipe, por projeto, por ambiente ou por servidor

Os quatro alcances das variáveis compartilhadas.

Team wide Vale para todos os recursos da equipe. Referência: {{team.NOME}}.
Project wide Vale para todos os ambientes de um projeto. Referência: {{project.NOME}}.
Environment wide Vale para os recursos de um ambiente. Referência: {{environment.NOME}}.
Server wide Vale para os recursos de um servidor. Referência: {{server.NOME}}.

A compartilhada não entra sozinha na aplicação: crie a variável na aplicação e use a referência como valor. A palavra do alcance é escrita assim mesmo; NOME é o nome da compartilhada.

LOJA_MOEDA={{project.LOJA_MOEDA}}

Na aplicação, o valor aponta para a variável LOJA_MOEDA compartilhada no projeto.

As variáveis que o Coolify cria

Com Include Coolify default variables marcado, a aplicação recebe variáveis com dados do deploy. Use essas em vez de escrever o endereço ou a porta à mão.

Variáveis predefinidas das aplicações
Variável	O que contém
COOLIFY_FQDN	Os domínios da aplicação
COOLIFY_URL	Os endereços (URLs) da aplicação
COOLIFY_BRANCH	O branch do Git publicado
COOLIFY_RESOURCE_UUID	O identificador do recurso no Coolify
COOLIFY_CONTAINER_NAME	O nome do contêiner
SOURCE_COMMIT	O commit publicado (fora do build, por padrão)
PORT	A primeira porta exposta, quando você não define PORT
HOST	0.0.0.0, quando você não define HOST

Aplique com Redeploy

Clique em Redeploy
A variável só chega à aplicação no próximo deploy. Com Changes pending no alto da página, clique em Redeploy (publicar de novo).

Guarde segredos com segurança

Nunca coloque senha ou chave de API no repositório. Deixe lá só um modelo, com valores como CHAVE-DE-EXEMPLO.
Use Lock (travar), na engrenagem da variável, para esconder o valor no painel.
Em Environment values in logs, deixe Hide all values (esconder todos os valores) para nada aparecer no log.
Para segredo usado no build, a documentação recomenda Build secrets em Docker BuildKit secrets.

O Lock é permanente

Travada, a variável não mostra mais o valor: ninguém consegue ver nem copiar. Dá para trocar por um valor novo, mas não para destravar. Guarde o valor num cofre de senhas antes.

Como saber se deu certo

A variável aparece na lista com Buildtime e Runtime como você escolheu, o Changes pending some depois do Redeploy e a aplicação lê o valor novo.

Problemas comuns

A aplicação não enxerga a variável nova

Causa provável: Faltou o Redeploy, ou a variável está marcada como Not available in the container.
O que fazer: Confira a coluna Runtime da lista e clique em Redeploy.

O build não encontra a variável

Causa provável: A variável está como Not available during build.
O que fazer: Abra a variável pela engrenagem, mude Build time para Available during build e clique em Redeploy.

Parte do valor sumiu, numa senha com $

Causa provável: Com Interpolate $VARIABLES, o trecho que começa com $ é lido como referência a outra variável.
O que fazer: Mude Interpolation para Literal (keep $ characters as-is) e clique em Redeploy.

A referência {{project.NOME}} chega à aplicação como texto

Causa provável: A variável compartilhada não existe, ou o nome e o alcance não batem. Referência sem par fica sem resolver.
O que fazer: Confira em Shared Variables o nome exato e o alcance.

Não resolveu? Veja os problemas comuns do Coolify ou abra um chamado na central do cliente.

Próximo passoComo criar um banco de dados no CoolifyDo grupo Databases ao banco rodando: imagem, nome, credenciais, o endereço interno para a aplicação e o acesso público, que fica fechado.

Fontes e documentação oficial

Coolify é um software de código aberto mantido pelo próprio projeto. Este manual é da Hospedagem Segura, para quem roda o Coolify nas nossas VPS, e foi conferido na versão 4.7.5.

Continue aprendendo

Ver todos os guias do Manual do Coolify

Rode o Coolify numa VPS da Hospedagem Segura

VPS Linux com acesso root, disco NVMe e IPv4 dedicado a partir de R$ 69,90/mês. Prefere a VPS pronta? No VPS Assistido, o Coolify vem instalado, com o painel no seu domínio, e a equipe ajuda no dia a dia.

Ver VPS para Coolify Conhecer o VPS Assistido