Variáveis de Ambiente

Este guia fornece uma visão detalhada das variáveis de ambiente necessárias para executar o SaaS Boilerplate. Configurar corretamente essas variáveis é essencial para funcionalidades como autenticação, conexões com banco de dados, processamento de pagamentos e muito mais.

Configurando Variáveis de Ambiente

O SaaS Boilerplate usa um arquivo .env para desenvolvimento local. Para começar:

1. Copie o arquivo de ambiente de exemplo:

cp .env.sample .env

2. Edite o arquivo .env com seus valores de configuração específicos

Variáveis de Ambiente Principais

Conexão com o Banco de Dados

# URL de conexão com PostgreSQL
DATABASE_URL="postgresql://docker:docker@localhost:5432/docker?schema=public"
NEXT_RUNTIME="nodejs"

Substitua o nome de usuário (docker), senha (docker), host (localhost), porta (5432) e nome do banco de dados (docker) com sua configuração específica.

Configuração da Aplicação

# Nome da sua aplicação
IGNITER_APP_NAME="SaaS Boilerplate"

# URL onde sua aplicação será executada
IGNITER_APP_URL=https://localhost:3000/

# Caminho onde sua API será executada
IGNITER_APP_BASE_PATH=/api/v1

# Chave secreta para JWT (Substitua por uma string aleatória)
IGNITER_APP_SECRET=sua_chave_secreta_aleatoria

# Ambiente da aplicação (development, production, test)
NODE_ENV="development"

Nota de Segurança: Em produção, sempre use um valor forte e único para IGNITER_APP_SECRET. Esta chave é usada para assinar JWTs e outras funcionalidades relacionadas à segurança.

Provedores de Autenticação

O SaaS Boilerplate suporta vários provedores OAuth para autenticação:

# Credenciais OAuth do GitHub
GITHUB_CLIENT_ID=seu_github_client_id
GITHUB_CLIENT_SECRET=seu_github_client_secret

# Credenciais OAuth do Google
GOOGLE_CLIENT_ID=seu_google_client_id
GOOGLE_CLIENT_SECRET=seu_google_client_secret

Configurando Provedores OAuth

Configuração do OAuth do Google:

1. Acesse o Console do Google Cloud
2. Crie um novo projeto ou selecione um existente
3. Navegue até API & Serviços > Credenciais
4. Crie um ID de Cliente OAuth 2.0
5. Adicione a URL da sua aplicação e a URL de callback (http://localhost:3000/api/auth/callback/google para desenvolvimento local)
6. Copie o ID do Cliente e o Segredo do Cliente para seu arquivo .env

Configuração do OAuth do GitHub:

1. Acesse as Configurações de Desenvolvedor do GitHub
2. Clique em "Novo Aplicativo OAuth"
3. Preencha os detalhes da aplicação
4. Defina a URL de callback como http://localhost:3000/api/auth/callback/github para desenvolvimento local
5. Copie o ID do Cliente e o Segredo do Cliente para seu arquivo .env

Provedores de Armazenamento

Para recursos de armazenamento de arquivos, você precisa configurar seu provedor de armazenamento:

STORAGE_ENDPOINT=http://localhost:9000
STORAGE_ACCESS_KEY_ID=sua_chave_de_acesso
STORAGE_SECRET_ACCESS_KEY=sua_chave_secreta
STORAGE_REGION=sua_regiao
STORAGE_BUCKET=nome_do_seu_bucket

Esta configuração funciona com MinIO para desenvolvimento local, ou com provedores de nuvem como AWS S3, Google Cloud Storage ou serviços similares em produção.

Provedores de Faturamento

Para processamento de pagamentos e gerenciamento de assinaturas, o SaaS Boilerplate usa o Stripe:

# Chave privada do Stripe
STRIPE_SECRET_KEY=

# Segredo do webhook para verificar eventos de webhook
STRIPE_WEBHOOK_SECRET=

# Chave pública para integração do Stripe no lado do cliente
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

Configurando o Stripe

1. Crie uma conta no Stripe
2. Obtenha suas chaves de API no Painel do Stripe
3. Configure seus produtos e preços no Painel do Stripe
4. Crie um endpoint de webhook e obtenha o segredo do webhook
5. Para testes locais, use a CLI do Stripe para encaminhar webhooks:

bun stripe:webhook

Usando Variáveis de Ambiente em Seu Código

O SaaS Boilerplate trabalha com Igniter.js, que fornece uma maneira segura em termos de tipos para acessar variáveis de ambiente:

// Exemplo de uso em seu código
import { env } from '@/igniter'

// Acesse variáveis de ambiente com segurança de tipos
const appUrl = env.IGNITER_APP_URL
const isDevelopment = env.NODE_ENV === 'development'

Variáveis de Ambiente Específicas

Você pode querer configurações diferentes para ambientes de desenvolvimento, teste e produção. O SaaS Boilerplate suporta múltiplos arquivos de ambiente:

• .env.development - Usado no modo de desenvolvimento
• .env.test - Usado ao executar testes
• .env.production - Usado em produção

Gerenciando Variáveis de Ambiente em Produção

Para implantações em produção, configure suas variáveis de ambiente através do painel do seu provedor de hospedagem:

• Vercel: Configure variáveis de ambiente nas configurações do seu projeto
• Netlify: Configure variáveis de ambiente no painel do Netlify
• AWS/GCP/Azure: Use seus respectivos serviços de gerenciamento de segredos

Solução de Problemas

Variáveis de Ambiente Não Estão Carregando

Se suas variáveis de ambiente não estiverem sendo carregadas corretamente:

1. Certifique-se de que seu arquivo .env está no diretório raiz
2. Verifique se há erros de sintaxe no seu arquivo .env
3. Reinicie seu servidor de desenvolvimento após fazer alterações
4. Verifique se não há espaços ao redor do sinal = nas definições das suas variáveis

Informações Sensíveis

Nunca faça commit do seu arquivo .env para o controle de versão. Certifique-se de que ele esteja incluído no seu arquivo .gitignore para evitar a exposição acidental de informações sensíveis.

Próximos Passos

Agora que você configurou suas variáveis de ambiente, pode prosseguir com:

• Desenvolvimento Local - Configure seu ambiente de desenvolvimento local
• Primeiros Passos - Comece a construir seu primeiro recurso