From 58db357cde9ce72b9515cfcee415f2f4398f0d54 Mon Sep 17 00:00:00 2001 From: Felipe Coutinho Date: Sun, 12 Apr 2026 01:49:40 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20reescrever=20README=20com=20guia=20de?= =?UTF-8?q?=20instala=C3=A7=C3=A3o=20para=20leigos;=20atualizar=20changelo?= =?UTF-8?q?g=202.3.7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- CHANGELOG.md | 2 + README.md | 156 +++++++++++++++++++++++++++++---------------------- package.json | 2 +- 3 files changed, 92 insertions(+), 68 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f82830..c1b22e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,8 @@ e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR ### 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 diff --git a/README.md b/README.md index 10e2cde..1484a02 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,12 @@ ## 📖 Índice - [Sobre o Projeto](#-sobre-o-projeto) -- [Instalação via Script](#-instalação-via-script) - - [Preparar o servidor (Ubuntu 24.04)](#-preparar-o-servidor-ubuntu-2404) -- [Início Rápido (manual)](#-início-rápido) +- [Como rodar o OpenMonetis](#-como-rodar-o-openmonetis) + - [Antes de tudo: preparar o servidor](#-antes-de-tudo-preparar-o-servidor-ubuntu-2404) + - [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á: -- Verificar Node, pnpm, Git e Docker -- Perguntar se quer banco local (Docker) ou remoto (Supabase, Neon, etc.) -- Gerar o `BETTER_AUTH_SECRET` automaticamente -- Configurar opcionais: Google OAuth, e-mail, IA, domínio público -- Clonar o repositório, instalar dependências e aplicar o schema +O assistente vai perguntar: +- Banco local (Docker) ou remoto (Supabase, Neon, Railway...)? +- URL da aplicação +- Google OAuth (opcional) +- E-mail via Resend (opcional) +- 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 -- Docker e Docker Compose +```bash +# 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 - git clone https://github.com/felipegcoutinho/openmonetis.git - cd openmonetis - pnpm install - ``` +Acesse em: `http://localhost:3000` -2. **Configure o `.env`** +--- - ```bash - cp .env.example .env - ``` +### Modo 4 — Banco remoto (Supabase, Neon, Railway...) - 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 - # Banco local (Docker): use host "localhost" - DATABASE_URL=postgresql://openmonetis:openmonetis_dev_password@localhost:5432/openmonetis_db +```bash +node setup.mjs # escolha "URL remota" e cole a URL do seu banco - # Banco remoto (Supabase, Neon, etc): use a URL completa do provider - # DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require +docker compose up +``` - 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 - docker compose up db -d - pnpm db:extensions - ``` - -4. **Execute as migrations e inicie** - - ```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. +| O que quero fazer | Comandos principais | +|---|---| +| 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` | +| Usar com banco remoto (Supabase etc.) | `node setup.mjs` → `docker compose up` | --- @@ -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) -# 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 +# 2. Subir (sem precisar de .env) 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 diff --git a/package.json b/package.json index 5ca92a3..db2fe91 100644 --- a/package.json +++ b/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",