​
Variáveis de Ambiente

Variáveis de ambiente (env vars) armazenam configurações sensíveis como API keys, database URLs e secrets. O Studio Next permite gerenciar env vars de forma segura.

​
O que são variáveis de ambiente

Variáveis de ambiente são pares chave-valor disponíveis no runtime da sua app: 
DATABASE_URL=postgresql://admin:pass@host:5432/mydb
API_KEY=sk-1234567890abcdef
PORT=3000
Nunca commit secrets no código. Use variáveis de ambiente para: - API keys
  • Database passwords - OAuth secrets - JWT secrets - Chaves de criptografia

​
Adicionando variáveis

​
Para apps deployadas

1

Acessar configurações da app

Vá em Deploy → clique na app → Settings → Environment Variables.
2

Adicionar variável

Clique em Add Variable. Preencha: - Key: nome da variável (ex: DATABASE_URL) - Value: valor da variável - Sensitive: marque para mascarar o valor
3

Salvar

Clique em Save. A variável é aplicada automaticamente (restart pode ser necessário).

​
Para VMs

Variáveis em VMs são definidas em:
  • /etc/environment (system-wide)
  • ~/.bashrc ou ~/.profile (user-specific)
  • Docker Compose environment: section
  • Systemd service EnvironmentFile
Exemplo Docker Compose: 
version: "3"
services:
  app:
    image: myapp:latest
    environment:
      - DATABASE_URL=postgresql://admin:pass@host:5432/mydb
      - API_KEY=sk-1234567890abcdef
      - PORT=3000
O Studio Next não gerencia env vars de VMs diretamente. Use SSH para editar arquivos de configuração.

​
Valores sensíveis

Quando você marca uma variável como Sensitive:
  • Valor é mascarado no dashboard (********)
  • Valor não aparece em logs
  • Valor é criptografado em trânsito e em repouso
  • Apenas usuários com permissão podem ver
Marque todas as variáveis sensíveis como Sensitive. Isso inclui: - Passwords - API keys - Tokens - Secrets

​
Build vs Runtime variables

O Studio Next distingue dois tipos:

​
Build-time variables

Disponíveis durante o build. Usadas para:
  • Configurar ambiente de build
  • Instalar dependências privadas
Exemplo: 
NPM_TOKEN=npm_1234567890abcdef
No package.json: 
{
  "dependencies": {
    "@myorg/private-package": "1.0.0"
  }
}
O npm usa NPM_TOKEN para baixar pacotes privados.
Build variables são expostas no build log. Não use para secrets sensíveis.

​
Runtime variables

Disponíveis quando a app está rodando. Usadas para:
  • Database URLs
  • API keys
  • Feature flags
Exemplo Node.js: 
const dbUrl = process.env.DATABASE_URL;
const port = process.env.PORT || 3000;
const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("API_KEY is required");
}
Runtime variables não aparecem em logs. Use para secrets.

​
Lendo variáveis no código

​
Node.js

// Ler variável
const apiKey = process.env.API_KEY;

// Com fallback
const port = process.env.PORT || 3000;

// Validar
if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL is required");
}

​
Python

import os

# Ler variável
api_key = os.environ.get('API_KEY')

# Com fallback
port = os.environ.get('PORT', '3000')

# Validar
database_url = os.environ.get('DATABASE_URL')
if not database_url:
    raise ValueError('DATABASE_URL is required')

​
Go

package main

import (
    "os"
    "fmt"
)

func main() {
    // Ler variável
    apiKey := os.Getenv("API_KEY")

    // Com fallback
    port := os.Getenv("PORT")
    if port == "" {
        port = "3000"
    }

    // Validar
    dbURL := os.Getenv("DATABASE_URL")
    if dbURL == "" {
        panic("DATABASE_URL is required")
    }
}

​
Atualizando variáveis

Quando você atualiza uma variável:
  1. A variável é atualizada no painel
  2. A app não reinicia automaticamente
  3. Você precisa reiniciar para aplicar
1

Atualizar variável

Em Settings → Environment Variables, clique no lápis ao lado da variável.
2

Editar valor

Altere o valor. Clique em Save.
3

Reiniciar app

Clique em Restart para aplicar a nova variável.
O restart causa downtime breve (5-10 segundos). Use blue-green deploy para zero downtime.

​
.env files

O Studio Next suporta import de arquivos .env:
1

Preparar arquivo .env

Crie um arquivo .env: bash DATABASE_URL=postgresql://admin:pass@host:5432/mydb API_KEY=sk-1234567890abcdef PORT=3000
2

Importar

Em Settings → Environment Variables, clique em Import .env. Selecione o arquivo. As variáveis são importadas automaticamente.
Não commit arquivos .env no Git. Adicione ao .gitignore:
# Environment variables
.env
.env.local
.env.*.local

​
Debugging

Se a variável não está sendo lida:

​
Boas práticas

  • Use nomes descritivos: DATABASE_URL em vez de DB - Agrupe por prefixo: AWS_ACCESS_KEY, AWS_SECRET_KEY - Documente: adicione comentários no código explicando cada variável - Valide no startup: lance erro se variável obrigatória faltar - Use Sensitive: marque todas as secrets - Não commite .env: use .gitignore

​
Próximos passos