Skip to main content

Envsubst | Linux

  • Envsubst | Linux

Visão geral​

envsubst é uma ferramenta de linha de comando, parte do pacote GNU gettext, utilizada para substituir variáveis de ambiente em textos. Ela é amplamente usada em scripts de shell, pipelines CI/CD e configurações de containers para gerar arquivos a partir de templates.

Em termos simples, o envsubst lê um texto de entrada e substitui variáveis como $VAR ou ${VAR} pelos valores definidos no ambiente.

Instalação​

Linux (Debian/Ubuntu)​

sudo apt install gettext

Linux (Alpine)​

apk add gettext

macOS (Homebrew)​

brew install gettext
brew link --force gettext

Sintaxe básica​

envsubst [OPÇÃO] < arquivo_entrada > arquivo_saida

Ou usando pipe:

cat arquivo_entrada | envsubst > arquivo_saida

Exemplo simples​

Template (config.template)​

API_URL=${API_URL}
PORT=$PORT

Definindo variáveis de ambiente​

export API_URL=https://api.exemplo.com
export PORT=8080

Executando envsubst​

envsubst < config.template > config.conf

Resultado (config.conf)​

API_URL=https://api.exemplo.com
PORT=8080

Substituir apenas variáveis específicas​

Por padrão, o envsubst substitui todas as variáveis encontradas. Para limitar quais variáveis serão substituídas:

envsubst '$API_URL $PORT' < config.template > config.conf

Isso é útil para evitar substituições acidentais.

Uso comum com Docker​

Exemplo em entrypoint​

#!/bin/sh
envsubst < /app/nginx.conf.template > /etc/nginx/nginx.conf
exec nginx -g "daemon off;"

Boas práticas​

  • Sempre valide se as variáveis necessárias estão definidas:

    : "${API_URL:?Variável API_URL não definida}"

  • Use templates com extensão .template para clareza.

  • Combine com set -e em scripts para evitar erros silenciosos.

  • Prefira ${VAR} em vez de $VAR para evitar ambiguidades.

Limitações​

  • Não suporta lógica condicional.
  • Não executa expressões ou funções.
  • Apenas substitui valores literais de variáveis de ambiente.

Para lógica mais complexa, considere ferramentas como jinja2, helm ou gomplate.

Quando usar envsubst​

  • Geração de arquivos de configuração simples
  • Ambientes Docker e Kubernetes
  • Pipelines CI/CD
  • Scripts de shell leves

Referência rápida​

envsubst            # substitui todas as variáveis
envsubst '$VAR'     # substitui apenas VAR