Variáveis de Ambiente

As variáveis de ambiente configuram suas aplicações sem colocar segredos no código. Elas são definidas por aplicação ou compartilhadas por um stack inteiro, armazenadas criptografadas e injetadas no contêiner na próxima implantação.

Adicionar variáveis

Uma chave usa letras maiúsculas, dígitos e sublinhados, e começa com uma letra ou um sublinhado (DATABASE_URL, _INTERNAL). Uma chave em minúsculas é recusada com 422.

Pelo painel

1. Abra a aplicação (Stacks, depois o stack e a aplicação) e a aba Ambiente.
2. No modo Chave-Valor, informe a chave e o valor. Marque Build se o valor só for necessário ao construir a imagem.
3. Clique em Adicionar variável. Os valores aparecem mascarados; Revelar os exibe e exige pelo menos o papel Developer na aplicação.

Pela CLI

sh0 env <app> set recebe um par CHAVE=VALOR e --build para uma variável de build; list nunca mostra os valores.

$ sh0 env my-api set LOG_LEVEL=info
[ok] Set LOG_LEVEL for 'my-api'
$ sh0 env my-api set GREETING_BUILD=hello --build
[ok] Set GREETING_BUILD for 'my-api'
$ sh0 env my-api list
  KEY             VALUE    BUILD  CREATED
  --------------  -------  -----  -------
  LOG_LEVEL       *******  no     0s ago
  GREETING_BUILD  *******  yes    0s ago

Pela API

As rotas são /api/v1/apps/:id/env-vars (GET, POST) e /api/v1/apps/:id/env-vars/:env_id (PATCH, DELETE). As respostas sempre mascaram o valor; adicione ?reveal=true ao GET para lê-lo.

$ curl -s -X POST https://panel.example.com/api/v1/apps/e17d4314-ff61-485a-a509-58b3974c1eee/env-vars \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"key":"DATABASE_URL","value":"postgres://app:[email protected]:5432/appdb"}'
{"data":{"app_id":"e17d4314-ff61-485a-a509-58b3974c1eee","created_at":"2026-10-02T02:49:26.463374291+00:00","id":"68ddf6a1-d9e0-49e4-9893-c320eaa58b62","is_build":false,"key":"DATABASE_URL","value":"*****"}}

$ curl -s -X PATCH https://panel.example.com/api/v1/apps/e17d4314-ff61-485a-a509-58b3974c1eee/env-vars/68ddf6a1-d9e0-49e4-9893-c320eaa58b62 \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"value":"postgres://app:[email protected]:5432/appdb"}'
{"data":{"app_id":"e17d4314-ff61-485a-a509-58b3974c1eee","created_at":"2026-10-02 02:49:26","id":"68ddf6a1-d9e0-49e4-9893-c320eaa58b62","is_build":false,"key":"DATABASE_URL","value":"*****"}}

Quando as mudanças valem

Salvar uma variável não reinicia nada. O contêiner em execução mantém o ambiente antigo até a próxima implantação, pelo painel ou com sh0 deploy <app>.

As variáveis de build são passadas ao docker build como --build-arg; o Dockerfile deve declará-las com ARG. Elas não existem no contêiner em execução. Para uma aplicação implantada por envio de arquivo (sh0 push), uma reimplantação reutiliza a última imagem: as variáveis de execução mudam, mas um novo valor de build só vale no próximo sh0 push.

Observado em uma aplicação de teste após reimplantação (a variável de build GREETING_BUILD chegou à imagem, não ao ambiente):

$ docker exec <container> env | grep -E '^(LOG_LEVEL|REGION|GREETING_BUILD)='
REGION=eu-central
LOG_LEVEL=info
$ docker exec <container> cat /build-arg.txt
hello

Edição em massa (.env)

A aba Ambiente aceita linhas CHAVE=VALOR, uma por linha; comentários (#) e linhas vazias são ignorados. As duas formas se comportam de modo diferente:

• Colar .env e depois Analisar e adicionar adiciona cada linha como nova variável e mantém as demais (uma chave existente é duplicada, veja acima).
• O Editor .env e depois Salvar tudo substitui todas as variáveis da aplicação pelo conteúdo do editor. O equivalente na API é PUT /api/v1/apps/:id/env-vars/bulk com um array entries: toda chave ausente do array é excluída.

Variáveis de stack

Uma variável definida em um stack é lida por todas as aplicações desse stack. Abra o stack e use Variáveis partilhadas no painel Rede interna e definições partilhadas, ou a API /api/v1/projects/:id/env-vars (um stack é um projeto na API). Enviar uma chave existente a atualiza. Os valores de stack nunca são devolvidos, nem a um administrador.

$ curl -s -X POST https://panel.example.com/api/v1/projects/5aee8eea-9f77-4d10-ac21-2fe4a565e666/env-vars \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"key":"REGION","value":"eu-central"}'
{"data":{"created_at":"2026-10-02 02:49:26","id":"e89e5915-e5dd-4878-b1b6-b6df150df54d","is_build":false,"key":"REGION","project_id":"5aee8eea-9f77-4d10-ac21-2fe4a565e666","updated_at":"2026-10-02 02:49:26"}}

Quando a mesma chave existe nos dois níveis, a aplicação vence, e o log de implantação lista as variáveis de stack sobrescritas. No exemplo abaixo, o stack define LOG_LEVEL=debug e REGION=eu-central, e a aplicação LOG_LEVEL=info:

Criptografia em repouso

Cada valor é criptografado com AES-256-GCM antes de ser gravado no banco do sh0. A chave é a chave mestra da instância, mantida em master.key e protegida por master.passphrase (PBKDF2), ambos no diretório de dados do sh0 (/var/lib/sh0 em uma instalação Linux padrão).

Conectar a outros serviços

O sh0 não expande referências: um valor como $OTHER_VAR chega ao contêiner como está. Escreva o valor completo usando os nomes de host internos: uma aplicação alcança outra do mesmo stack em <nome-app> ou <nome-app>.internal, e qualquer servidor de banco de dados em <nome-servidor>.internal.

O que o sh0 não injeta

• Nenhuma variável de sistema. O sh0 não adiciona variáveis SH0_* (nome da aplicação, domínio, commit) aos seus contêineres. Única exceção: uma aplicação Laravel ou Lumen sem APP_KEY recebe uma, gerada na primeira implantação e salva como variável da aplicação.
• Variáveis em tarefas agendadas. Uma tarefa vinculada a um aplicativo recebe as variáveis de execução do aplicativo e do projeto, em um contêiner descartável criado a partir da imagem do aplicativo: veja Tarefas agendadas.