jbandClaude Opus 4.8
25137eb5da
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>
114 lines
5.5 KiB
Markdown
114 lines
5.5 KiB
Markdown
# 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.
|