docs: add Portuguese docs and English CLAUDE.md

Add README.md, docs/ (fluxo, configuracao, arquitetura) in PT-BR and a CLAUDE.md technical reference in English describing the installer flow, generated files, containers and architecture. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-19 11:53:56 -03:00
parent 009c4bc8d1
commit 25137eb5da
5 changed files with 675 additions and 0 deletions
@@ -0,0 +1,122 @@
+# Arquitetura Interna
+
+Visão de como o código está organizado. A aplicação segue o padrão
+[The Elm Architecture](https://github.com/charmbracelet/bubbletea) (Model–Update–View)
+da biblioteca Bubble Tea.
+
+## Estrutura de pastas
+
+```
+.
+├── cmd/
+│   └── main.go            # Ponto de entrada; inicia o programa Bubble Tea
+├── internal/tui/
+│   ├── model.go           # Struct Model, ConfigValues, carga de defaults, InitialModel/Init
+│   ├── steps.go           # Enum das etapas do assistente
+│   ├── update.go          # Lógica de transição (Update) por etapa
+│   ├── view.go            # Renderização (View) por etapa
+│   ├── form.go            # Componente genérico de formulário (FormStep/FormField)
+│   ├── cmds.go            # Mensagens (Msg) e comandos assíncronos (tea.Cmd)
+│   ├── docker.go          # Wrappers de chamadas ao binário docker
+│   ├── config.go          # Geração e gravação de config.toml e envs
+│   └── styles.go          # Paleta de cores e estilos Lip Gloss
+├── config.toml            # (gerado em runtime; ignorado no git)
+├── envs                   # (gerado em runtime, vproxy)
+└── Makefile               # Build multiplataforma e publicação no S3
+```
+
+## Componentes principais
+
+### `Model` ([model.go](../internal/tui/model.go))
+
+Estado único da aplicação. Campos relevantes:
+
+- `currentStep` — etapa atual do assistente.
+- Estado de progresso/flags: `dockerInstalled`, `downloadDone`, `finishedFile`,
+  `finishedDockerRun`, e os respectivos erros.
+- Um `FormStep` por etapa de formulário (`loginForm`, `wireguardForm`, `appForm`,
+  `serverForm`, `dbForm`, `certForm`).
+- `configValues` (`ConfigValues`) — acumula os valores de todos os formulários,
+  agrupados por seção.
+
+`loadConfig()` define os **valores padrão** e, se houver um `config.toml` no diretório,
+sobrescreve com o conteúdo dele (usando `BurntSushi/toml`). `InitialModel()` constrói
+todos os formulários com esses defaults.
+
+### Etapas ([steps.go](../internal/tui/steps.go))
+
+`step` é um enum (`iota`) que define a ordem do assistente. O `Update` faz o dispatch
+com base em `currentStep`. Ver [fluxo.md](fluxo.md) para o detalhamento.
+
+### Update ([update.go](../internal/tui/update.go))
+
+`Update` trata primeiro mensagens globais (`Ctrl+C`, `WindowSizeMsg`, tick do spinner)
+e depois delega para um handler por etapa (ex.: `updateCheckDocker`,
+`updateDownloadImage`, `updateRunDocker`). As transições de etapa acontecem ao
+concluir formulários (`done == true`) ou ao receber mensagens de conclusão dos
+comandos assíncronos.
+
+Constantes importantes ficam no topo do arquivo:
+
+- `imageName` / `wireguardImageName` — imagens no registry privado.
+- `configPath` (`config.toml`) / `wireguardConfigPath` (`envs`).
+
+### View ([view.go](../internal/tui/view.go))
+
+`View` monta a tela com cabeçalho fixo, corpo dependente da etapa e rodapé de ajuda.
+Usa `AltScreen`. Cada etapa tem um método `viewXxx` ou reutiliza o `View()` do
+formulário.
+
+### Formulário genérico ([form.go](../internal/tui/form.go))
+
+`FormStep` agrupa vários `FormField`. Suporta os tipos texto, senha, número e seleção.
+`Update` cuida da navegação entre campos (`Tab`/setas) e retorna `done = true` quando
+o `Enter` é pressionado no último campo. `Values()` devolve um `map[string]string`
+indexado pelo `Id` de cada campo — é isso que alimenta o `ConfigValues`.
+
+### Comandos e mensagens ([cmds.go](../internal/tui/cmds.go))
+
+Toda operação bloqueante (chamar `docker`, escrever arquivo) é encapsulada em um
+`tea.Cmd` que roda em goroutine e devolve uma `Msg` ao loop do Bubble Tea:
+
+| Comando                       | Ação                                  | Mensagem de retorno         |
+| ----------------------------- | ------------------------------------- | --------------------------- |
+| `CheckDockerCmd`              | `exec.LookPath("docker")`             | `DockerCheckedMsg`          |
+| `DownloadImageCmd`            | `docker login` + `pull` (app)         | `ImageDownloadFinishedMsg`  |
+| `DownloadWireguardImageCmd`   | `docker login` + `pull` (vproxy)      | `ImageDownloadFinishedMsg`  |
+| `GenerateConfigFile`          | grava `config.toml`                   | `ConfigFileMsg`             |
+| `GenerateWireguardConfigFile` | grava `envs`                          | `ConfigFileMsg`             |
+| `RunAppContainer`             | `docker run` (app)                    | `DockerRunMsg`              |
+| `RunWireguardContainer`       | `docker run` (vproxy)                 | `DockerRunMsg`              |
+| `TickCmd`                     | tick da barra de progresso            | `TickMsg`                   |
+
+### Camada Docker ([docker.go](../internal/tui/docker.go))
+
+Funções utilitárias que invocam o binário `docker` via `os/exec`:
+
+- `EnsureNetwork` — cria a rede `app-dono_app` se necessário.
+- `RunAppClienteContainer` / `RunWireguardDockerContainer` — montam os argumentos do
+  `docker run`, removem container homônimo prévio e verificam o status `running`.
+- `verifyContainerRunning` — inspeciona o status e, em falha, anexa os últimos logs.
+- `removeExistingContainer`, `PullImage`, `ImageExists`, `PushFileToContainer`.
+
+### Estilos ([styles.go](../internal/tui/styles.go))
+
+Paleta de cores e estilos Lip Gloss reutilizados na View (títulos, cursor, ajuda,
+erros, barra de progresso, seleção).
+
+## Dependências
+
+- `charm.land/bubbletea/v2` — runtime TUI (loop Model/Update/View).
+- `charm.land/bubbles/v2` — componentes (`textinput`, `spinner`).
+- `charm.land/lipgloss/v2` — estilização.
+- `github.com/BurntSushi/toml` — leitura do `config.toml` para defaults.
+
+## Observações para manutenção
+
+- **Porta:** o `config.toml` grava `port = 8080` fixo; a porta do formulário só afeta o
+  mapeamento de host no `docker run`. Ver [configuracao.md](configuracao.md).
+- **Credenciais:** o login do registry é coletado uma vez e reutilizado para baixar a
+  imagem do vproxy.
+- **Rede:** o nome da rede é a constante `networkName` (`app-dono_app`) em `docker.go`;
+  usar sempre a constante ao referenciá-la.
@@ -0,0 +1,96 @@
+# Referência de Configuração
+
+Este documento descreve todos os campos coletados pelo instalador e os arquivos que
+ele gera.
+
+## Arquivo `config.toml`
+
+Gerado por `GenerateConfigTOML` em
+[`internal/tui/config.go`](../internal/tui/config.go) e montado no container do app em
+`/app/config.toml`. Se um `config.toml` já existir no diretório ao iniciar o
+instalador, seus valores são usados como **padrão** nos formulários.
+
+### `[server]`
+
+| Campo             | Origem (formulário)           | Observações                                                  |
+| ----------------- | ----------------------------- | ------------------------------------------------------------ |
+| `port`            | **fixo `8080`** no arquivo    | A porta do formulário é usada apenas no **mapeamento do host** (`<porta>:8080`). Dentro do container o app sempre escuta na `8080`. |
+| `timeout_seconds` | Servidor → Timeout            | Em segundos. Padrão `30`.                                    |
+| `environment`     | Servidor → Ambiente           | `development` ou `production`.                                |
+
+> **Atenção:** o campo "Porta" do formulário define a porta exposta no host, não a
+> porta interna. O `config.toml` sempre grava `port = 8080`.
+
+### `[database]`
+
+| Campo       | Origem               | Observações                          |
+| ----------- | -------------------- | ------------------------------------ |
+| `type`      | Banco → Tipo do Banco| `postgres` ou `oracle`.              |
+| `url`       | Banco → URL de acesso| String de conexão completa.          |
+| `max_conns` | Banco → Conexões máx.| Validado como número.                |
+| `min_conns` | Banco → Conexões mín.| Validado como número.                |
+
+### `[certificate]`
+
+| Campo        | Valor                                | Observações                                  |
+| ------------ | ------------------------------------ | -------------------------------------------- |
+| `mapped_dir` | Certificado → Diretório              | Diretório local montado em `/app/certs`.     |
+| `cert_path`  | `/app/certs/client.crt` (fixo)       | Caminho **dentro** do container.             |
+| `key_path`   | `/app/certs/client.key` (fixo)       | Caminho **dentro** do container.             |
+| `ca_path`    | `/app/certs/ca.crt` (fixo)           | Caminho **dentro** do container.             |
+
+O diretório indicado deve conter os arquivos `client.crt`, `client.key` e `ca.crt`
+(comunicação mTLS com o servidor central).
+
+### `[application]`
+
+| Campo                | Origem                          | Observações                          |
+| -------------------- | ------------------------------- | ------------------------------------ |
+| `erp`                | `TOTVS` (fixo)                  | ERP integrado.                       |
+| `central_server_url` | Aplicação → URL Servidor Central| Ex.: `https://app-dono-api.vitruvio.com.br:8443`. |
+| `enrollment_token`   | Aplicação → Token de Inscrição  | Gerado no painel web.                |
+
+### `[log]`
+
+| Campo    | Valor             |
+| -------- | ----------------- |
+| `level`  | `debug` (fixo)    |
+| `format` | `json` (fixo)     |
+
+## Arquivo `envs` (vproxy / WireGuard)
+
+Gerado por `GenerateWireguardConfig` apenas quando **não há IP público**. Passado ao
+container do vproxy via `--env-file`.
+
+| Variável     | Origem                  | Observações                                                  |
+| ------------ | ----------------------- | ------------------------------------------------------------ |
+| `PRIVKEY`    | vproxy → Chave Privada  | Chave privada WireGuard.                                     |
+| `VIP`        | vproxy → IP Virtual     | Padrão `127.0.0.1`.                                          |
+| `PSK`        | vproxy → Pre-Shared Key | Chave pré-compartilhada.                                     |
+| `PROXY_EDPS` | vproxy → Proxy EDPS     | Mapeamento de portas, ex.: `22:127.0.0.1:22`.               |
+| `MTU`        | vproxy → MTU            | Opcional. Padrão `1380`. Validado como número.              |
+| `PROTO`      | vproxy → Protocolo      | `UDP` (padrão) ou `TCP`.                                     |
+
+### Sobre o protocolo
+
+- **UDP** (padrão): melhor desempenho e estabilidade. Manter sempre que possível.
+- **TCP**: usar apenas quando firewalls restritivos bloqueiam o tráfego UDP e não for
+  possível negociar a liberação com o cliente.
+
+## Campo "Modo Compatibilidade"
+
+Presente no formulário de Servidor (`seccomp_unconfined`). Quando definido como
+**`Sim`**, os containers sobem com `--security-opt seccomp=unconfined`. Útil em
+máquinas antigas onde o perfil seccomp padrão do Docker causa falhas. Aplica-se tanto
+ao container do app quanto ao do vproxy.
+
+## Tipos de campo dos formulários
+
+Definidos em [`internal/tui/form.go`](../internal/tui/form.go):
+
+| Tipo               | Comportamento                                  |
+| ------------------ | ---------------------------------------------- |
+| `FieldTypeText`    | Texto livre.                                   |
+| `FieldTypePassword`| Texto mascarado.                               |
+| `FieldTypeNumber`  | Texto (validação numérica na gravação).        |
+| `FieldTypeSelect`  | Opções alternadas com `←`/`→`.                 |
@@ -0,0 +1,113 @@
+# Fluxo do Instalador
+
+Este documento detalha cada etapa do assistente, a ordem em que ocorrem e as ações
+executadas em segundo plano. As etapas são definidas em
+[`internal/tui/steps.go`](../internal/tui/steps.go).
+
+## Visão geral das etapas
+
+| #  | Etapa (`step`)               | O que acontece                                                       |
+| -- | ---------------------------- | ------------------------------------------------------------------- |
+| 1  | `StepCheckDocker`            | Verifica se o binário `docker` está no `PATH`.                       |
+| 2  | `StepDockerInstall`          | Tela final exibida quando o Docker não é encontrado.                 |
+| 3  | `StepDockerLogin`            | Formulário de login no registry privado.                            |
+| 4  | `StepDownloadImage`          | `docker login` + `docker pull` da imagem do app cliente.            |
+| 5  | `StepIPQuestion`             | Pergunta se há IP público disponível.                               |
+| 6  | `StepWireguardConfig`        | Formulário de configuração do vproxy (apenas sem IP público).       |
+| 7  | `StepGenerateWireguardFile`  | Gera o arquivo `envs`.                                               |
+| 8  | `StepDownloadWireguard`      | `docker login` + `docker pull` da imagem do vproxy.                 |
+| 9  | `StepRunWireguard`           | Sobe o container `vproxy`.                                           |
+| 10 | `StepAppConfig`              | Formulário da aplicação (URL central, token).                       |
+| 11 | `StepServerConfig`           | Formulário do servidor (porta, timeout, ambiente, compatibilidade). |
+| 12 | `StepDatabaseConfig`         | Formulário do banco de dados.                                       |
+| 13 | `StepCertConfig`             | Formulário do diretório de certificados.                            |
+| 14 | `StepGenerateFile`           | Gera o `config.toml`.                                                |
+| 15 | `StepRunDocker`              | Sobe o container `app-dono-cliente`.                                 |
+| 16 | `StepDone`                   | Mensagem de sucesso.                                                 |
+
+## Detalhamento
+
+### 1. Verificação do Docker (`StepCheckDocker`)
+
+Ao iniciar, o `Init()` dispara três comandos em paralelo: `CheckDockerCmd`,
+`TickCmd` (anima a barra de progresso) e o tick do spinner. O `CheckDockerCmd`
+executa `exec.LookPath("docker")`.
+
+- **Encontrado:** ao pressionar qualquer tecla, segue para o login.
+- **Não encontrado:** vai para `StepDockerInstall`, que orienta a instalação manual
+  e encerra. O instalador **não** instala o Docker.
+
+### 3–4. Login e download da imagem do app
+
+O formulário coleta usuário e senha do registry. Em seguida, `DownloadImageCmd`
+executa:
+
+```
+docker login hub.davinti.com.br:443/app-dono/app-cliente:latest -u <user> -p <senha>
+docker pull  hub.davinti.com.br:443/app-dono/app-cliente:latest
+```
+
+As **mesmas credenciais** são reaproveitadas mais adiante para baixar a imagem do
+vproxy. Em caso de erro de login ou pull, a mensagem do Docker é exibida e o
+instalador encerra ao pressionar qualquer tecla.
+
+### 5. Pergunta de IP público (`StepIPQuestion`)
+
+- **Sim** → pula o bloco do vproxy e vai direto para `StepAppConfig`.
+- **Não** → vai para `StepWireguardConfig`.
+
+### 6–9. Bloco vproxy (somente sem IP público)
+
+1. **`StepWireguardConfig`** — coleta `PRIVKEY`, `VIP`, `PSK`, `PROXY_EDPS`, `MTU`
+   e `PROTO` (UDP/TCP).
+2. **`StepGenerateWireguardFile`** — grava o arquivo `envs`
+   (ver [`config.go`](../internal/tui/config.go), `GenerateWireguardConfig`).
+3. **`StepDownloadWireguard`** — faz login e pull da imagem `davinti-vproxy`.
+4. **`StepRunWireguard`** — sobe o container `vproxy` com `--cap-add=NET_ADMIN`,
+   `--device /dev/net/tun`, `--env-file envs` e o conecta à rede `app-dono_app`.
+   Após subir, espera 2s e verifica se o status é `running`; se não, mostra os
+   últimos logs do container.
+
+Ao final do bloco, segue para `StepAppConfig`.
+
+### 10–13. Configuração da aplicação
+
+Quatro formulários sequenciais preenchem o `ConfigValues`:
+
+- **Aplicação:** URL do servidor central e token de inscrição.
+- **Servidor:** porta, timeout, ambiente (`development`/`production`) e modo
+  compatibilidade (`seccomp=unconfined`).
+- **Banco de dados:** tipo (`postgres`/`oracle`), URL de conexão, conexões máx./mín.
+- **Certificado:** diretório local com os certificados mTLS.
+
+### 14. Geração do `config.toml` (`StepGenerateFile`)
+
+`WriteConfigFile` valida os campos numéricos (`port`, `timeout`, `max_conns`,
+`min_conns`) e grava o `config.toml`. Em caso de valor inválido, exibe o erro e
+permite tentar novamente.
+
+### 15. Subida do container do app (`StepRunDocker`)
+
+`RunAppClienteContainer` remove um container homônimo existente, garante a rede
+`app-dono_app`, e executa `docker run` com:
+
+- usuário/grupo do host (`-u uid:gid`);
+- mapeamento de porta `<porta do host>:8080`;
+- volume do `config.toml` em `/app/config.toml`;
+- volume do diretório de certificados em `/app/certs`;
+- `--restart unless-stopped`.
+
+Verifica o status `running` da mesma forma que o vproxy.
+
+### 16. Conclusão (`StepDone`)
+
+Exibe "Instalação realizada com sucesso!". Qualquer tecla encerra.
+
+## Tratamento de erros
+
+Em etapas de download, geração de arquivo e subida de container, qualquer falha:
+
+- interrompe o avanço automático;
+- mostra a mensagem/erro do Docker (ou do sistema de arquivos) com estilo de erro;
+- permite **sair** (em downloads) ou **tentar novamente** (em geração/run) conforme
+  a etapa.