Configuração do Ambiente

Todas as configurações ficam no arquivo .env. Nunca edite o código para mudar senhas ou chaves.

Criar o arquivo .env

bash

cp EXEMPLO.env .env

Nunca suba o .env para o Git

O arquivo .env já está no .gitignore. Ele contém senhas e secrets — nunca deve ser versionado.

Aplicação

Variável	Exemplo	Descrição
`APP_NAME`	`"Vupi.us API"`	Nome da aplicação exibido no dashboard e e-mails.
`APP_ENV`	`production`	`production`, `development` ou `testing`. Em produção ativa validações extras de segurança.
`APP_DEBUG`	`false`	`true` exibe stack traces. Sempre `false` em produção.
`APP_URL`	`https://api.vupi.us`	URL base da API. Usada em e-mails, CORS e sitemap.
`APP_URL_FRONTEND`	`https://meusite.com`	URL do frontend. Adicionada automaticamente ao CORS.
`APP_PORT`	`3005`	Porta do servidor PHP.
`APP_TIMEZONE`	`America/Bahia`	Fuso horário para datas e logs.
`CORS_ALLOWED_ORIGINS`	`https://meusite.com`	Origens permitidas para CORS, separadas por vírgula.
`TRUST_PROXY`	`true`	`true` quando há proxy reverso (Caddy/Nginx). Confia em `X-Forwarded-Proto`.

Banco de dados (core)

Variável	Exemplo	Descrição
`DB_CONEXAO`	`postgresql`	Driver: `postgresql` ou `mysql`.
`DB_HOST`	`localhost`	Host do banco de dados.
`DB_PORT`	`5432`	Porta. PostgreSQL: 5432, MySQL: 3306.
`DB_NOME`	`vupi_db`	Nome do banco de dados.
`DB_USUARIO`	`admin`	Usuário do banco.
`DB_SENHA`	`senha_forte`	Senha do banco. Mínimo 16 caracteres em produção com banco remoto.

Banco de dados (modules) — opcional

Permite que módulos externos usem um banco separado do core. Deixe DB2_NOME vazio para usar o mesmo banco do core.

Variável	Descrição
`DB2_CONEXAO`	Driver do segundo banco (`postgresql` ou `mysql`).
`DB2_HOST`, `DB2_PORT`	Host e porta do segundo banco.
`DB2_NOME`	Nome do banco. Se vazio, usa o banco core.
`DB2_USUARIO`, `DB2_SENHA`	Credenciais do segundo banco.

Configurações Avançadas de Banco

Variável	Padrão	Descrição
`DEFAULT_MODULE_CONNECTION`	`modules`	`core` ou `modules`. Define qual banco os módulos usam por padrão.
`MIGRATE_LOCK_TIMEOUT`	`10`	Timeout em segundos para obter o lock que evita migrations simultâneas.

Quando usar dois bancos?

Use DB2_* quando quiser separar dados do kernel (usuários, auth, auditoria) dos dados dos módulos (produtos, pedidos, etc.). Útil para compliance, backup seletivo ou performance.

JWT e Segurança

Secrets obrigatórios em produção

JWT_SECRET e JWT_API_SECRET devem ter no mínimo 32 caracteres. O sistema recusa iniciar em produção com valores fracos.

Variável	Exemplo	Descrição
`JWT_SECRET`	`abc123...64chars`	Secret para tokens de usuários. Gere com `openssl rand -hex 32`.
`JWT_API_SECRET`	`xyz789...64chars`	Secret para tokens de admin_system. Deve ser diferente do JWT_SECRET.
`JWT_ISSUER`	`https://api.vupi.us`	Identificador do emissor do token (claim `iss`). Validado em toda requisição.
`JWT_AUDIENCE`	`https://api.vupi.us`	Audiência do token (claim `aud`). Validado em toda requisição.
`JWT_EXPIRATION_TIME`	`3600`	Expiração do access token em segundos (padrão atual: 1 hora).
`REFRESH_TOKEN_EXPIRATION_SECONDS`	`2592000`	Expiração do refresh token (padrão: 30 dias).
`COOKIE_SECURE`	`true`	`true` em produção com HTTPS. Cookies só enviados via HTTPS.
`COOKIE_SAMESITE`	`Lax`	`Lax` (mesmo domínio) ou `None` (domínios diferentes, requer Secure=true).

Key Rotation (Avançado)

O sistema suporta rotação de secrets JWT sem downtime. Tokens assinados com secrets antigos continuam válidos enquanto novos tokens usam o secret atual.

Variável	Exemplo	Descrição
`JWT_SECRET_KID`	`v2`	ID da chave ativa (v1, v2, v3...). Define qual secret usar para novos tokens.
`JWT_SECRET_v1`	`secret_antigo`	Secret anterior. Tokens assinados com v1 ainda são válidos.
`JWT_SECRET_v2`	`secret_atual`	Secret atual. Usado para assinar novos tokens quando KID=v2.
`JWT_SECRET_v3`	`secret_futuro`	Secret futuro (opcional). Permite preparar próxima rotação.
`REVOCATION_STORAGE`	`database`	`database` ou `redis`. Define onde armazenar tokens revogados.

Como fazer key rotation

1. Adicione JWT_SECRET_v2 com novo secret
2. Defina JWT_SECRET_KID=v2
3. Aguarde a expiração dos tokens antigos conforme JWT_EXPIRATION_TIME
4. Remova JWT_SECRET_v1 do .env

E-mail (SMTP)

Variável	Exemplo	Descrição
`MAILER_HOST`	`smtp.gmail.com`	Servidor SMTP.
`MAILER_PORT`	`587`	Porta SMTP. 587 para TLS, 465 para SSL.
`MAILER_USERNAME`	`[email protected]`	Usuário SMTP.
`MAILER_PASSWORD`	`app_password`	Senha SMTP. Para Gmail, use uma App Password.
`MAILER_FROM_EMAIL`	`[email protected]`	E-mail remetente.
`MAILER_FROM_NAME`	`"Vupi.us API"`	Nome do remetente.

Admin padrão (seeder)

Obrigatório em produção

Em APP_ENV=production, o seeder aborta se ADMIN_PASSWORD estiver vazio. Em desenvolvimento usa Admin@123456 como padrão.

Variável	Exemplo	Descrição
`ADMIN_EMAIL`	`[email protected]`	E-mail do administrador criado pelo seeder.
`ADMIN_PASSWORD`	`MinhaS3nh@Forte!`	Senha do admin. Obrigatório em produção.
`ADMIN_NAME`	`Administrador`	Nome completo do admin.
`ADMIN_USERNAME`	`admin`	Username do admin.

Redis (opcional)

Configure Redis para habilitar rate limiting distribuído entre múltiplos containers. Sem Redis, o sistema usa armazenamento em arquivo (servidor único).

Variável	Padrão	Descrição
`REDIS_HOST`	vazio	Host do Redis. Deixe vazio para usar file storage.
`REDIS_PORT`	`6379`	Porta do Redis.
`REDIS_PASSWORD`	vazio	Senha do Redis (se configurada).
`REDIS_PREFIX`	`vupi:`	Prefixo das chaves no Redis.

Vupi.us IDE

Configurações da IDE integrada para criação de módulos no navegador.

Variável	Padrão	Descrição
`IDE_MAX_PROJECTS_PER_USER`	`1`	Máximo de projetos por usuário. Use `-1` para ilimitado e `0` para bloquear criação.

Integrações Externas

Variável	Descrição
`GOOGLE_CLIENT_ID`	Client ID do Google Cloud Console (para OAuth no módulo LinkEncurtador).
`SECURITY_ALERT_WEBHOOK`	URL do webhook para alertas de segurança (Slack, Discord, etc.). Opcional.
`TURNSTILE_SITE_KEY`	Chave pública usada pelo widget de login e recuperação de senha.
`TURNSTILE_SECRET`	Chave privada validada somente no servidor; nunca deve ir para o frontend ou Git.
`TURNSTILE_HOSTNAMES`	Hostnames aceitos na resposta da Cloudflare, separados por vírgula.

Configurar Google OAuth

1. Acesse Google Cloud Console
2. Crie um projeto ou selecione existente
3. Ative a API "Google+ API"
4. Crie credenciais OAuth 2.0
5. Adicione https://seudominio.com nas origens autorizadas

Gerar secrets JWT

bash

# Gera JWT_SECRET (64 chars hex)
openssl rand -hex 32

# Gera JWT_API_SECRET (64 chars hex)
openssl rand -hex 32

# Ou via CLI do projeto (gera automaticamente se vazios)
php vupi setup --auto --jwt=if-empty