docs: reescrever README com guia de instalação para leigos; atualizar changelog 2.3.7

- README: seção "Como rodar" reescrita com 4 modos explicados para leigos
- README: seção Docker atualizada (sem .env obrigatório, localhost funciona)
- package.json: corrigir env:setup apontando para setup-env.sh deletado → setup.mjs
- CHANGELOG 2.3.7: documentar fix do localhost→db e default DATABASE_URL

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.env.example

@@ -48,7 +48,6 @@ GOOGLE_CLIENT_SECRET=
 # Umami: https://umami.is — self-hosted ou cloud
 UMAMI_URL=
 UMAMI_WEBSITE_ID=
-# Domínios rastreados (ex: openmonetis.com) — corresponde ao data-domains do script
 UMAMI_DOMAINS=
 
 # === AI Providers (Opcional) ===

CHANGELOG.md

@@ -15,6 +15,7 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR
 - Lançamentos: filtro por status de pagamento (somente pagos / somente não pagos) e filtro por presença de anexo
 - Lançamentos: indicador visual no status de liquidação para lançamentos de cartão de crédito com fatura paga — exibe ícone verde com tooltip explicativo
 - Scripts: `scripts/install-deps.sh` — script de preparação para servidores Ubuntu 24.04 limpos (instala Docker, Node.js 22, pnpm via Homebrew)
+- Docker: variáveis `PUBLIC_DOMAIN`, `UMAMI_URL`, `UMAMI_WEBSITE_ID` e `UMAMI_DOMAINS` passadas ao container da aplicação no `docker-compose.yml`
 
 ### Alterado
 
@@ -32,6 +33,15 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR
 - S3: corrigido `Error: Region is missing` ao usar o app sem S3 configurado — `S3_REGION` vazio (string vazia) não era tratado pelo operador `??`; substituído por `||` em todo o `s3-client.ts`
 - i18n: corrigidas mensagens de erro que exibiam "Payer" em inglês em vez de "Pagador"
 - Logos: corrigido modal seletor de logos de cartões e contas para renderizar miniaturas sem avisos de proporção
+- Scripts: `install-deps.sh` — spinner travava o script por `wait` retornar código não-zero com `set -e` ativo; corrigido com `|| true`
+- Scripts: `install-deps.sh` — prompt interativo do corepack suprimido com `COREPACK_ENABLE_DOWNLOAD_PROMPT=0`
+- Scripts: `install-deps.sh` — PATH do Homebrew não estava configurado na seção de resumo
+
+### Removido
+
+- Scripts: removidos arquivos órfãos `scripts/dev.ts` e `scripts/setup-env.sh` (substituídos pelo `setup.mjs`)
+- Docker: `docker-compose.yml` agora funciona sem arquivo `.env` — `DATABASE_URL` tem valor padrão com credenciais de desenvolvimento
+- Docker: `docker-entrypoint.sh` converte automaticamente `@localhost:` para `@db:` na `DATABASE_URL` ao iniciar o container, eliminando a necessidade de usar hosts diferentes no `.env` para desenvolvimento local e Docker
 
 ## [2.3.6] - 2026-04-09
 

README.md

@@ -32,9 +32,12 @@
 ## 📖 Índice
 
 - [Sobre o Projeto](#-sobre-o-projeto)
-- [Instalação via Script](#-instalação-via-script)
+- [Como rodar o OpenMonetis](#-como-rodar-o-openmonetis)
-  - [Preparar o servidor (Ubuntu 24.04)](#-preparar-o-servidor-ubuntu-2404)
+  - [Antes de tudo: preparar o servidor](#-antes-de-tudo-preparar-o-servidor-ubuntu-2404)
-- [Início Rápido (manual)](#-início-rápido)
+  - [Modo 1 — Só quero usar](#modo-1--só-quero-usar-sem-mexer-no-código)
+  - [Modo 2 — Quero configurar opcionais](#modo-2--quero-configurar-opcionais-oauth-e-mail-ia)
+  - [Modo 3 — Quero contribuir com o código](#modo-3--quero-contribuir-com-o-código)
+  - [Modo 4 — Banco remoto](#modo-4--banco-remoto-supabase-neon-railway)
 - [Scripts Disponíveis](#-scripts-disponíveis)
 - [Docker](#-docker)
 - [Backup](#-backup)
@@ -103,22 +106,24 @@ A ideia é simples: ter um lugar onde consigo ver todas as minhas contas, cartõ
 
 ---
 
-## ⚡ Instalação via Script
+## 🚀 Como rodar o OpenMonetis
 
-A forma mais rápida de instalar. O script verifica dependências, configura o `.env` interativamente e sobe o banco automaticamente.
+O OpenMonetis precisa de dois serviços funcionando ao mesmo tempo para operar: **o app** (a interface e a lógica do sistema) e **o banco de dados** (onde ficam guardados seus lançamentos, contas, categorias etc.). Existem algumas formas de subir os dois, dependendo do que você quer fazer.
 
-### 🖥️ Preparar o servidor (Ubuntu 24.04)
+---
 
-Se você está num **servidor Ubuntu limpo** (VPS, Oracle Cloud, DigitalOcean...) sem Node.js, Docker ou pnpm instalados, use o script de preparação antes de continuar.
+### 🖥️ Antes de tudo: preparar o servidor (Ubuntu 24.04)
 
-> ⚠️ **Testado apenas em Ubuntu Server 24.04 LTS.** Em outras distribuições ou versões é necessário testar ou ajustar o script.
+Se você está em um **servidor Ubuntu limpo** (VPS, Oracle Cloud, DigitalOcean...) sem Docker, Node.js ou pnpm instalados, rode esse script primeiro. Ele instala tudo que é necessário automaticamente e pula o que já estiver presente.
+
+> ⚠️ **Testado apenas em Ubuntu Server 24.04 LTS.** Em outras distribuições ou versões, instale as dependências manualmente.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/scripts/install-deps.sh -o install-deps.sh
 sudo sh install-deps.sh
 ```
 
-O script instala (e pula o que já estiver presente):
+O script instala:
 
 | Ferramenta | Como instala |
 |---|---|
@@ -128,10 +133,34 @@ O script instala (e pula o que já estiver presente):
 | Node.js 22 | Via Homebrew |
 | pnpm | Via corepack |
 
-Após a conclusão, adiciona o usuário atual ao grupo `docker` — faça logout/login para ativar. Em seguida, prossiga com o `setup.mjs` abaixo.
+Ao final, o usuário atual é adicionado ao grupo `docker` — faça **logout e login** para a mudança ter efeito antes de continuar.
+
+Se já tiver Docker e Node.js 22+ instalados, pule essa etapa.
 
 ---
 
+### Modo 1 — Só quero usar (sem mexer no código)
+
+Esse é o caminho mais simples. Você baixa apenas um arquivo de configuração e o Docker faz o resto: baixa a imagem do app pronta do Docker Hub e sobe o banco automaticamente. **Não precisa clonar o repositório nem instalar dependências.**
+
+```bash
+# 1. Baixa o arquivo de configuração
+curl -fsSL https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/docker-compose.yml -o docker-compose.yml
+
+# 2. Sobe o app e o banco juntos
+docker compose --profile local up
+```
+
+Acesse em: `http://localhost:3000`
+
+> O banco sobe com as credenciais padrão. Se quiser usar uma senha personalizada, crie um arquivo `.env` na mesma pasta antes de subir — veja a seção [Variáveis de Ambiente](#-variáveis-de-ambiente).
+
+---
+
+### Modo 2 — Quero configurar opcionais (OAuth, e-mail, IA)
+
+Se quiser ativar login com Google, envio de e-mails, integrações com IA ou outras configurações, use o assistente interativo. Ele faz perguntas passo a passo e gera o arquivo `.env` com tudo preenchido corretamente.
+
 **Pré-requisito:** Node.js 22+
 
 ```bash
@@ -142,68 +171,64 @@ curl -fsSL https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/se
 curl -o setup.mjs https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/setup.mjs ; node setup.mjs
 ```
 
-O script irá:
+O assistente vai perguntar:
-- Verificar Node, pnpm, Git e Docker
+- Banco local (Docker) ou remoto (Supabase, Neon, Railway...)?
-- Perguntar se quer banco local (Docker) ou remoto (Supabase, Neon, etc.)
+- URL da aplicação
-- Gerar o `BETTER_AUTH_SECRET` automaticamente
+- Google OAuth (opcional)
-- Configurar opcionais: Google OAuth, e-mail, IA, domínio público
+- E-mail via Resend (opcional)
-- Clonar o repositório, instalar dependências e aplicar o schema
+- Chaves de IA — Claude, GPT, Gemini, OpenRouter (opcional)
+- Domínio público separado para landing page (opcional)
+
+Ao final, ele clona o repositório, instala as dependências e aplica o schema no banco. Depois é só subir:
+
+```bash
+cd openmonetis
+docker compose --profile local up
+```
 
 ---
 
-## 🚀 Início Rápido (manual)
+### Modo 3 — Quero contribuir com o código
 
-### Pré-requisitos
+Nesse modo o Next.js roda **direto no seu servidor com hot-reload** — toda vez que você salva um arquivo, o sistema atualiza automaticamente sem precisar reiniciar nada. O banco continua rodando dentro do Docker (mais simples), só o app fica fora.
 
-- Node.js 22+ e pnpm
+```bash
-- Docker e Docker Compose
+# 1. Clona o repositório e roda o assistente de configuração
+git clone https://github.com/felipegcoutinho/openmonetis.git
+cd openmonetis
+node setup.mjs
 
-### Passo a Passo
+# 2. Sobe apenas o banco em background (o app vai rodar fora do Docker)
+pnpm docker:up:db
 
-1. **Clone e instale**
+# 3. Inicia o app com hot-reload
+pnpm dev
+```
 
-   ```bash
+Acesse em: `http://localhost:3000`
-   git clone https://github.com/felipegcoutinho/openmonetis.git
-   cd openmonetis
-   pnpm install
-   ```
 
-2. **Configure o `.env`**
+---
 
-   ```bash
+### Modo 4 — Banco remoto (Supabase, Neon, Railway...)
-   cp .env.example .env
-   ```
 
-   Edite o `.env` com suas credenciais. O principal é o `DATABASE_URL` e o `BETTER_AUTH_SECRET`:
+Se você já tem um banco PostgreSQL hospedado em algum serviço externo, não precisa rodar o banco localmente. Informe a URL do banco durante o `setup.mjs` (escolha a opção "URL remota") e suba só o app:
 
-   ```env
+```bash
-   # Banco local (Docker): use host "localhost"
+node setup.mjs   # escolha "URL remota" e cole a URL do seu banco
-   DATABASE_URL=postgresql://openmonetis:openmonetis_dev_password@localhost:5432/openmonetis_db
 
-   # Banco remoto (Supabase, Neon, etc): use a URL completa do provider
+docker compose up
-   # DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require
+```
 
-   BETTER_AUTH_SECRET=seu-secret-aqui  # gere com: openssl rand -base64 32
+---
-   BETTER_AUTH_URL=http://localhost:3000
-   ```
 
-3. **Suba o banco de dados** (pule se estiver usando banco remoto)
+### Comparativo
 
-   ```bash
+| O que quero fazer | Comandos principais |
-   docker compose up db -d
+|---|---|
-   pnpm db:extensions
+| Só usar, da forma mais simples | `docker-compose.yml` → `docker compose --profile local up` |
-   ```
+| Usar com Google OAuth, e-mail ou IA | `node setup.mjs` → `docker compose --profile local up` |
-
+| Desenvolver e contribuir com o código | `node setup.mjs` → `pnpm docker:up:db` → `pnpm dev` |
-4. **Execute as migrations e inicie**
+| Usar com banco remoto (Supabase etc.) | `node setup.mjs` → `docker compose up` |
-
-   ```bash
-   pnpm db:push
-   pnpm dev
-   ```
-
-5. Acesse `http://localhost:3000`
-
-> **Docker completo** (app + banco em containers): use `pnpm docker:up:local` ao invés dos passos 3-4.
 
 ---
 
@@ -263,27 +288,24 @@ Health checks configurados para ambos os serviços (PostgreSQL via `pg_isready`,
 
 **Modo 1 — App + banco local (recomendado para self-hosting)**
 
-Puxa a imagem pronta do Docker Hub e sobe app + banco juntos. Não precisa de Node.js instalado.
+Puxa a imagem pronta do Docker Hub e sobe app + banco juntos. Não precisa de Node.js instalado nem de arquivo `.env` para começar — as credenciais padrão já estão configuradas.
 
 ```bash
 # 1. Baixar o docker-compose.yml
 curl -fsSL https://raw.githubusercontent.com/felipegcoutinho/openmonetis/main/docker-compose.yml -o docker-compose.yml
 
-# 2. Criar o .env (copie o .env.example como referência)
+# 2. Subir (sem precisar de .env)
-# DATABASE_URL=postgresql://openmonetis:SUA_SENHA@db:5432/openmonetis_db
-# POSTGRES_PASSWORD=SUA_SENHA
-# BETTER_AUTH_SECRET=string-longa-aleatoria
-# BETTER_AUTH_URL=http://localhost:3000
-
-# 3. Subir
 docker compose --profile local up
+
 # ou, se tiver o projeto clonado:
 pnpm docker:up:local
 ```
 
+> Se quiser personalizar senhas ou ativar opcionais, crie um arquivo `.env` na mesma pasta antes de subir. Veja a seção [Variáveis de Ambiente](#-variáveis-de-ambiente).
+
 **Modo 2 — App com banco remoto**
 
-Use quando o banco está em um provider externo (Supabase, Neon, Railway...).
+Use quando o banco está em um provider externo (Supabase, Neon, Railway...). Configure o `DATABASE_URL` no `.env` com a URL do seu banco e suba só o app.
 
 ```bash
 # DATABASE_URL deve apontar para o banco remoto no .env
@@ -292,11 +314,11 @@ docker compose up
 
 **Modo 3 — Build local (desenvolvimento)**
 
-Builda a imagem localmente a partir do código-fonte.
+Builda a imagem localmente a partir do código-fonte em vez de usar a imagem do Docker Hub. Útil para testar mudanças antes de publicar.
 
 ```bash
-pnpm docker:up        # app apenas (banco separado)
 pnpm docker:up:db     # sobe o banco em background
+pnpm docker:up        # builda e sobe o app localmente
 ```
 
 ### Comandos úteis

docker-compose.yml

@@ -81,7 +81,8 @@ services:
       NODE_ENV: production
 
       # Banco local: use host "db" | Banco remoto: URL completa do provider
-      DATABASE_URL: ${DATABASE_URL}
+      # O entrypoint converte automaticamente "localhost" → "db" se necessário
+      DATABASE_URL: ${DATABASE_URL:-postgresql://openmonetis:openmonetis_dev_password@db:5432/openmonetis_db}
 
       BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
       BETTER_AUTH_URL: ${BETTER_AUTH_URL:-http://localhost:3000}
@@ -109,6 +110,14 @@ services:
       GOOGLE_GENERATIVE_AI_API_KEY: ${GOOGLE_GENERATIVE_AI_API_KEY:-}
       OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}
 
+      # Multi-domínio (opcional)
+      PUBLIC_DOMAIN: ${PUBLIC_DOMAIN:-}
+
+      # Analytics (opcional)
+      UMAMI_URL: ${UMAMI_URL:-}
+      UMAMI_WEBSITE_ID: ${UMAMI_WEBSITE_ID:-}
+      UMAMI_DOMAINS: ${UMAMI_DOMAINS:-}
+
     # required: false permite subir sem banco local (banco remoto via DATABASE_URL)
     depends_on:
       db:

docker-entrypoint.sh

@@ -1,5 +1,13 @@
 #!/bin/sh
 
+# Dentro do container Docker, "localhost" não alcança o serviço de banco.
+# Substitui automaticamente para o nome do serviço "db" da rede Docker.
+# Não afeta URLs de bancos remotos (não contêm "@localhost:").
+if [ -n "$DATABASE_URL" ]; then
+  DATABASE_URL=$(echo "$DATABASE_URL" | sed 's|@localhost:|@db:|g')
+  export DATABASE_URL
+fi
+
 echo "Rodando migrations..."
 RETRIES=5
 until NODE_PATH=/app/migrate/node_modules /app/migrate/node_modules/.bin/drizzle-kit push || [ "$RETRIES" -eq 0 ]; do

package.json

@@ -11,7 +11,7 @@
 		"lint": "biome check .",
 		"lint:deadcode": "knip --reporter compact",
 		"lint:fix": "biome check --write .",
-		"env:setup": "bash scripts/setup-env.sh",
+		"env:setup": "node setup.mjs",
 		"db:generate": "drizzle-kit generate",
 		"db:migrate": "drizzle-kit migrate",
 		"db:push": "drizzle-kit push",

scripts/dev.ts

@@ -1,17 +0,0 @@
-#!/usr/bin/env tsx
-
-import { execSync } from "node:child_process";
-import { config } from "dotenv";
-
-// Carregar variáveis de ambiente
-config();
-
-const port = process.env.PORT || "3000";
-
-console.log(`Starting Next.js development server on port ${port}...`);
-
-// Executar next dev com a porta especificada
-execSync(`npx next dev --turbopack --port ${port}`, {
-	stdio: "inherit",
-	env: { ...process.env, PORT: port },
-});

scripts/install-deps.sh

@@ -9,6 +9,9 @@ set -e
 LOG_FILE="/tmp/openmonetis-install.log"
 > "$LOG_FILE"
 
+# Suprimir prompt interativo do corepack ao chamar pnpm/node versioning
+export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+
 # ── Cores ──────────────────────────────────────────────────────────────────────
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
@@ -51,8 +54,8 @@ spinner_start() {
 
 spinner_stop() {
   if [ -n "$_spin_pid" ]; then
-    kill "$_spin_pid" 2>/dev/null
+    kill "$_spin_pid" 2>/dev/null || true
-    wait "$_spin_pid" 2>/dev/null
+    wait "$_spin_pid" 2>/dev/null || true
     _spin_pid=""
     printf "\r\033[2K"
   fi
@@ -220,15 +223,19 @@ if command -v pnpm > /dev/null 2>&1; then
 else
   if [ -n "$CURRENT_USER" ] && [ "$CURRENT_USER" != "root" ]; then
     run_as_user "Instalando pnpm via corepack" \
-      'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" && corepack enable && corepack prepare pnpm@latest --activate'
+      'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" && corepack enable && COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack prepare pnpm@latest --activate'
   else
     run_quiet "Instalando pnpm via corepack" \
-      sh -c 'corepack enable && corepack prepare pnpm@latest --activate'
+      sh -c 'corepack enable && COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack prepare pnpm@latest --activate'
   fi
   ok "pnpm instalado"
 fi
 
 # ── Resumo ─────────────────────────────────────────────────────────────────────
+# Garantir que node/pnpm do brew estejam no PATH para o resumo
+export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"
+eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" 2>/dev/null || true
+
 printf "\n${BOLD}Concluído em $(elapsed)${RESET}\n"
 
 ok "git:            $(git --version | cut -d' ' -f3)"
@@ -236,6 +243,3 @@ ok "docker:         $(docker --version | cut -d',' -f1 | cut -d' ' -f3)"
 ok "docker compose: $(docker compose version | cut -d' ' -f4)"
 ok "node:           $(node --version)"
 ok "pnpm:           $(pnpm --version)"
-
-printf "\n${CYAN}Próximo passo:${RESET}\n"
-printf "  node setup.mjs\n\n"

scripts/setup-env.sh

@@ -1,49 +0,0 @@
-#!/bin/bash
-
-# Script para configurar ambiente de forma segura
-# Cria backup do .env atual antes de sobrescrever
-
-set -e
-
-echo "🔧 Configurando ambiente..."
-
-# Se .env já existe, criar backup
-if [ -f .env ]; then
-  BACKUP_FILE=".env.backup.$(date +%Y%m%d_%H%M%S)"
-  echo "⚠️  Arquivo .env existente detectado!"
-  echo "📦 Criando backup em: $BACKUP_FILE"
-  cp .env "$BACKUP_FILE"
-  echo "✅ Backup criado com sucesso!"
-  echo ""
-  read -p "Deseja sobrescrever o .env atual com .env.example? (s/N) " -n 1 -r
-  echo
-  if [[ ! $REPLY =~ ^[Ss]$ ]]; then
-    echo "❌ Operação cancelada. Seu .env não foi modificado."
-    exit 0
-  fi
-fi
-
-# Copiar .env.example para .env
-if [ -f .env.example ]; then
-  cp .env.example .env
-  echo "✅ Arquivo .env criado a partir de .env.example"
-else
-  echo "❌ Erro: .env.example não encontrado!"
-  exit 1
-fi
-
-# Gerar BETTER_AUTH_SECRET automaticamente
-if command -v openssl &> /dev/null; then
-  SECRET=$(openssl rand -base64 32)
-  sed -i.bak "s|BETTER_AUTH_SECRET=.*|BETTER_AUTH_SECRET=$SECRET|" .env && rm -f .env.bak
-  echo "✅ BETTER_AUTH_SECRET gerado automaticamente"
-else
-  echo "⚠️  openssl não encontrado — configure BETTER_AUTH_SECRET manualmente:"
-  echo "   openssl rand -base64 32"
-fi
-
-echo ""
-echo "⚠️  IMPORTANTE: Edite o arquivo .env e configure:"
-echo "   - DATABASE_URL"
-echo "   - BETTER_AUTH_URL"
-echo "   - Demais variáveis opcionais (OAuth, e-mail, IA)"