Variáveis de Ambiente

Variáveis de ambiente são a principal forma de configurar suas aplicações no sh0. Todos os valores são criptografados em repouso usando AES-256-GCM, e você pode defini-los para aplicações individuais ou compartilhá-los em toda a stack.

Adicionando Variáveis de Ambiente

Você pode adicionar variáveis de ambiente pelo dashboard ou pela API. As variáveis são injetadas nos seus containers na inicialização e estão disponíveis para sua aplicação como variáveis de ambiente padrão.

Pelo Painel

1. Navegue até seu app (ou stack para variáveis compartilhadas).
2. Abra a aba Ambiente.
3. Clique em Adicionar Variável.
4. Insira o nome e o valor da variável.
5. Clique em Salvar.

Pela API

# Add a single variable
curl -X POST http://localhost:9000/api/apps/APP_ID/env \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "DATABASE_URL", "value": "postgres://user:pass@db:5432/myapp"}'

# Add multiple variables at once
curl -X POST http://localhost:9000/api/apps/APP_ID/env/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": [
    {"key": "NODE_ENV", "value": "production"},\n    {"key": "PORT", "value": "3000"},\n    {"key": "SECRET_KEY", "value": "your-secret-key"}
  ]}'

Criptografia em Repouso

Todos os valores de variáveis de ambiente são criptografados antes de serem armazenados no banco de dados do sh0. O sh0 usa criptografia AES-256-GCM (Galois/Counter Mode) com um nonce único por valor.

Isso significa que, mesmo que alguém obtenha acesso ao arquivo de banco de dados do sh0, não poderá ler seus segredos sem a chave de criptografia. A chave mestra é gerada na primeira inicialização e armazenada separadamente do banco de dados.

Importação em Lote (Arquivo .env)

Se você tem um arquivo .env existente, pode importar todas as variáveis de uma vez:

1. Vá à aba Environment do seu app ou stack.
2. Clique em Import .env.
3. Cole o conteúdo do seu arquivo .env ou faça upload do arquivo diretamente.
4. Revise as variáveis parseadas — sh0 mostrará o que será adicionado, atualizado ou ignorado.
5. Clique em Import para aplicar.

O parser de importação suporta a sintaxe padrão do .env incluindo:

# Comments are ignored
DATABASE_URL=postgres://user:pass@db:5432/myapp
SECRET_KEY="value with spaces"
MULTILINE="line1\nline2"

# Empty values are supported
EMPTY_VAR=

# Quotes are stripped automatically
QUOTED='single quotes work too'

Escopo de Variáveis

Variáveis de ambiente podem ser definidas em dois níveis, e o escopo mais específico sempre prevalece:

Variáveis em Nível de Stack

Variáveis em nível de stack são herdadas por todas as aplicações na stack. Use-as para configurações compartilhadas:

• Strings de conexão de banco de dados compartilhadas por várias aplicações
• Chaves de API usadas em todo o projeto
• Identificadores de ambiente (APP_ENV=production)
• Feature flags que se aplicam a todo o projeto

Variáveis a Nível de App

Variáveis a nível de app são específicas de um único app e sobrescrevem qualquer variável a nível de stack com o mesmo nome:

• Números de porta (PORT=3000)
• Chaves API específicas do app
• Configuração que difere entre frontend e backend

Referenciando Entre Aplicações

Aplicações dentro da mesma stack podem se comunicar usando o nome da aplicação como hostname na rede interna do Docker. O sh0 também oferece uma forma de referenciar variáveis de uma aplicação a partir de outra usando sintaxe de template:

# In the 'frontend' app, reference the 'api' app's port:
API_URL=http://api:${api.PORT}

# Reference the database connection from the 'db' service:
DATABASE_HOST=${db.HOSTNAME}

O padrão mais comum é usar o hostname interno diretamente, já que todas as aplicações em uma stack compartilham uma rede Docker:

# In your frontend app's env vars:
API_URL=http://api:3000

# In your API app's env vars:
DATABASE_URL=postgres://user:pass@db:5432/myapp
REDIS_URL=redis://cache:6379

Variáveis de Sistema

O sh0 injeta automaticamente um conjunto de variáveis de sistema somente leitura em cada contêiner:

Boas Práticas