@acropole/skills 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +181 -2
- package/agents/revisor-deploy.md +73 -0
- package/agents/revisor-documentacao.md +78 -0
- package/agents/revisor-orfeu.md +80 -0
- package/agents/revisor-trismegisto.md +81 -0
- package/bin/install.js +252 -0
- package/package.json +15 -4
- package/skills/acropole/SKILL.md +80 -0
- package/skills/acropole/references/arquitetura.md +174 -0
- package/skills/acropole/references/fluxos/app-novo.md +34 -0
- package/skills/acropole/references/fluxos/doctor.md +55 -0
- package/skills/acropole/references/fluxos/endpoint-novo.md +22 -0
- package/skills/acropole/references/fluxos/revisar.md +56 -0
- package/skills/acropole/references/fluxos/tela-nova.md +27 -0
- package/skills/acropole/scripts/doctor.mjs +439 -0
- package/skills/angular/SKILL.md +155 -0
- package/skills/angular/references/armadilhas.md +99 -0
- package/skills/angular/references/dados.md +251 -0
- package/skills/angular/references/estrutura.md +279 -0
- package/skills/angular/references/features.md +219 -0
- package/skills/angular/references/testes-build.md +257 -0
- package/skills/angular/scripts/checar.mjs +182 -0
- package/skills/angular/scripts/nucleo.mjs +227 -0
- package/skills/apollo/SKILL.md +226 -0
- package/skills/apollo/references/armadilhas.md +99 -0
- package/skills/apollo/references/envelope-erros.md +120 -0
- package/skills/apollo/references/estrutura-bootstrap.md +310 -0
- package/skills/apollo/references/schema-resolvers.md +183 -0
- package/skills/apollo/references/subscriptions.md +224 -0
- package/skills/apollo/references/testes-build.md +181 -0
- package/skills/apollo/scripts/checar.mjs +160 -0
- package/skills/apollo/scripts/nucleo.mjs +227 -0
- package/skills/docker/SKILL.md +102 -0
- package/skills/docker/references/modelos.md +251 -0
- package/skills/docker/references/porques.md +286 -0
- package/skills/documentacao/SKILL.md +146 -0
- package/skills/documentacao/references/checklist-coerencia.md +59 -0
- package/skills/documentacao/references/ligar-app-novo.md +107 -0
- package/skills/documentacao/references/modelo-especificacao.md +51 -0
- package/skills/documentacao/references/modelo-readme.md +75 -0
- package/skills/documentacao/scripts/checar.mjs +454 -0
- package/skills/documentacao/scripts/nucleo.mjs +227 -0
- package/skills/express/SKILL.md +156 -0
- package/skills/express/references/dados.md +180 -0
- package/skills/express/references/estrutura.md +157 -0
- package/skills/express/references/middlewares.md +227 -0
- package/skills/express/references/rotas-erros.md +286 -0
- package/skills/express/references/testes-deploy.md +154 -0
- package/skills/express/scripts/checar.mjs +115 -0
- package/skills/express/scripts/nucleo.mjs +227 -0
- package/skills/fastapi/SKILL.md +132 -0
- package/skills/fastapi/references/banco.md +197 -0
- package/skills/fastapi/references/estrutura.md +325 -0
- package/skills/fastapi/references/integracoes.md +145 -0
- package/skills/fastapi/references/rotas-erros.md +140 -0
- package/skills/fastapi/references/testes-deploy.md +190 -0
- package/skills/fastapi/scripts/checar.mjs +108 -0
- package/skills/fastapi/scripts/nucleo.mjs +227 -0
- package/skills/hefesto/SKILL.md +119 -0
- package/skills/hefesto/references/conceitos.md +131 -0
- package/skills/hefesto/references/diagnostico.md +70 -0
- package/skills/hefesto/references/fluxo.md +122 -0
- package/skills/hefesto/references/preparar-app.md +105 -0
- package/skills/orfeu/SKILL.md +162 -0
- package/skills/orfeu/references/angular-api.md +201 -0
- package/skills/orfeu/references/angular-armadilhas.md +116 -0
- package/skills/orfeu/references/angular-recipes.md +474 -0
- package/skills/orfeu/references/angular.md +212 -0
- package/skills/orfeu/references/diferencas.md +56 -0
- package/skills/orfeu/references/node-api.md +354 -0
- package/skills/orfeu/references/node-armadilhas.md +158 -0
- package/skills/orfeu/references/node-recipes.md +541 -0
- package/skills/orfeu/references/node.md +204 -0
- package/skills/orfeu/references/python-api.md +346 -0
- package/skills/orfeu/references/python-recipes.md +479 -0
- package/skills/orfeu/references/python.md +240 -0
- package/skills/orfeu/scripts/checar.mjs +126 -0
- package/skills/orfeu/scripts/nucleo.mjs +227 -0
- package/skills/trismegisto/SKILL.md +194 -0
- package/skills/trismegisto/references/angular-api.md +2788 -0
- package/skills/trismegisto/references/angular-exports.md +4020 -0
- package/skills/trismegisto/references/angular-recipes.md +1883 -0
- package/skills/trismegisto/references/angular-types.md +492 -0
- package/skills/trismegisto/references/angular.md +390 -0
- package/skills/trismegisto/references/catalogo/icones.json +912 -0
- package/skills/trismegisto/references/catalogo/seletores.json +7013 -0
- package/skills/trismegisto/references/catalogo/tokens.json +240 -0
- package/skills/trismegisto/references/spine-api.md +1530 -0
- package/skills/trismegisto/references/spine-recipes.md +581 -0
- package/skills/trismegisto/references/spine.md +343 -0
- package/skills/trismegisto/scripts/checar.mjs +216 -0
- package/skills/trismegisto/scripts/nucleo.mjs +227 -0
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hefesto
|
|
3
|
+
description: Processo de deploy pela plataforma Hefesto (build pelo Ciclope, entrega pelo Talos, roteamento pelo Caddy de cada origin) — conceitos (projeto, aplicação service/site, repositório por ambiente, registry, origin, agent com path, worker, domínio, variáveis por ambiente, grupos), o que um app precisa ter para ser implantado, solicitações de Deploy/Redeploy, versões e tags de imagem, rollback, logs e diagnóstico de falhas. Use ao preparar um app para entrar no Hefesto, cadastrar ou revisar o deploy dele, ou investigar build/deploy/rota que falhou. Não use para escrever o Dockerfile em si (use docker), nem para o código do app (angular, express, apollo, fastapi) ou autenticação (orfeu).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# hefesto
|
|
7
|
+
|
|
8
|
+
O Hefesto é a plataforma que leva um app do repositório git até um container (ou um site estático)
|
|
9
|
+
servido atrás de um Caddy. Três peças:
|
|
10
|
+
|
|
11
|
+
| Peça | Papel | Onde roda |
|
|
12
|
+
| --- | --- | --- |
|
|
13
|
+
| **Hefesto** (server + UI) | cadastro, versões, solicitações, histórico, gera o Caddyfile | central |
|
|
14
|
+
| **Ciclope** (builder) | `git clone` → `podman build` → `podman push` para o registry | um só, perto do código-fonte |
|
|
15
|
+
| **Talos** (agente) | `podman pull` → `podman run` (service) ou extrai `/dist` (site); mantém o Caddy do servidor | um por servidor (origin) |
|
|
16
|
+
|
|
17
|
+
O Ciclope nunca roda app; o Talos nunca builda nem acessa o git. A imagem no **registry** é o
|
|
18
|
+
contrato entre os dois: o que não foi publicado lá não pode ser implantado.
|
|
19
|
+
|
|
20
|
+
Skills relacionadas: **docker** (como escrever o Dockerfile que o Hefesto builda), **fastapi**,
|
|
21
|
+
**express**, **apollo**, **angular** (o app em si), **orfeu** (identidade do app no Argos, auditoria
|
|
22
|
+
e o flush dela no SIGTERM).
|
|
23
|
+
|
|
24
|
+
## Regras essenciais
|
|
25
|
+
|
|
26
|
+
1. **Um app = um Dockerfile buildável sem nada além do clone.** O Ciclope clona só o branch
|
|
27
|
+
configurado (`--depth 1`) e builda na raiz do repo ou no `build_path` (subpasta, para monorepo).
|
|
28
|
+
Nada de arquivo gerado localmente, `.env` ou `.npmrc` com credencial. Ver **docker**.
|
|
29
|
+
2. **Tipo do app decide o alvo do build.** `service`: estágio final do Dockerfile, vira container.
|
|
30
|
+
`site`: o Ciclope builda `--target site` com `--build-arg CONFIGURATION=<nome do ambiente>`;
|
|
31
|
+
o estágio `site` tem o build estático em **`/dist` na raiz da imagem** e nunca roda.
|
|
32
|
+
3. **A porta cadastrada no app é a porta em que o processo escuta dentro do container**, em
|
|
33
|
+
`0.0.0.0`. O Caddy encaminha para `<nome-do-container>:<porta do app>` pela rede interna; a porta
|
|
34
|
+
do worker é só o mapeamento no host. O Hefesto **não injeta `PORT`**: deixe o `ENV PORT` do
|
|
35
|
+
Dockerfile igual ao cadastro (ou cadastre a variável).
|
|
36
|
+
4. **O path do agent chega inteiro no service** (o Caddy usa `handle`, sem tirar o prefixo). Um
|
|
37
|
+
service publicado em `/meu-app/api` precisa responder em `/meu-app/api/...` (prefixo configurável
|
|
38
|
+
no app: `API_PREFIX`, `root_path`, `CONTEXT_PATH`). Para **site** o prefixo é removido, mas o
|
|
39
|
+
`baseHref` do Angular tem que ser o próprio path, senão os assets saem da raiz e dão 404.
|
|
40
|
+
5. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
|
|
41
|
+
`podman run` por um `--env-file` temporário (600, apagado logo depois; nunca `-e K=V` no argv) —
|
|
42
|
+
**só no próximo deploy/redeploy/rollback**. Arquivos `.env.*` não vão para a imagem
|
|
43
|
+
(`.dockerignore`). Segredo **sem valor padrão** no Dockerfile/código: faltou no cadastro, o app cai na
|
|
44
|
+
subida em vez de aceitar `changeme`.
|
|
45
|
+
6. **Processo principal recebe o SIGTERM.** Toda troca de versão faz `podman stop` (10 s de prazo e
|
|
46
|
+
depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
|
|
47
|
+
perde a fila de auditoria do Orfeu e atrasa todo deploy. Ver **docker**.
|
|
48
|
+
7. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O Talos
|
|
49
|
+
não espera health: "Deploy concluído" significa container criado, não app saudável — confira.
|
|
50
|
+
8. **Versão é do registry**: tag `<ambiente>-<major>.<minor>.<fix>.<test>` (ex.: `homol-1.4.0.2`).
|
|
51
|
+
O build escolhe qual parte incrementar; a retenção mantém só as últimas N por ambiente (padrão 5),
|
|
52
|
+
menos as que algum worker está rodando. Rollback só para versão que ainda existe no registry.
|
|
53
|
+
9. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
|
|
54
|
+
workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
|
|
55
|
+
distribuído. Ver `references/preparar-app.md`.
|
|
56
|
+
|
|
57
|
+
## Fluxo em uma tela
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
Solicitação "Deploy de Serviços|Sites" Início → Build → Deploy → Fim
|
|
61
|
+
Solicitação "Redeploy de Serviços|Sites" Início → Deploy → Fim (sem build: última versão)
|
|
62
|
+
|
|
63
|
+
Início valida app, agent, worker e se o repositório é do MESMO ambiente do origin do worker
|
|
64
|
+
Build Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
|
|
65
|
+
→ push <registry>/<app>:<ambiente>-<versão> → retenção das antigas
|
|
66
|
+
Deploy Hefesto → Talos do origin: pull da versão mais nova do ambiente
|
|
67
|
+
service: stop + rm do container antigo → run -d --restart unless-stopped -e ... -p host:app
|
|
68
|
+
site: create (sem rodar) → copia /dist para o volume do Caddy
|
|
69
|
+
→ Hefesto regenera o Caddyfile do origin e o Talos recarrega o Caddy (sem downtime)
|
|
70
|
+
Rollback mesmo passo Deploy, com uma versão escolhida da lista do registry
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Cada etapa grava o histórico (`current` → `processing` → `success`/`error`, com a mensagem) e
|
|
74
|
+
publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
|
|
75
|
+
|
|
76
|
+
## Checklist antes do primeiro deploy
|
|
77
|
+
|
|
78
|
+
- [ ] Dockerfile na raiz do repo (ou do `build_path`), `.dockerignore` com `.git`, dependências
|
|
79
|
+
locais, `dist` e `.env*`. Para site: estágio chamado `site` com `/dist`.
|
|
80
|
+
- [ ] Site: uma configuração do Angular **com o nome exato de cada ambiente** do Hefesto
|
|
81
|
+
(`dev`, `homol`, `prod`...), com `baseHref` igual ao path do agent.
|
|
82
|
+
- [ ] Service: escuta em `0.0.0.0:<porta cadastrada>`, responde sob o path do agent, tem
|
|
83
|
+
`/health`, trata SIGTERM, CMD em forma exec.
|
|
84
|
+
- [ ] Nenhum segredo com valor padrão (`ENV X=changeme`, `getenv("X", "...")`); `.gitattributes` com
|
|
85
|
+
`*.sh text eol=lf` se houver script.
|
|
86
|
+
- [ ] Projeto e aplicação cadastrados (`app_name` é imutável: vira nome da imagem e do container).
|
|
87
|
+
- [ ] Conector git com token de leitura; repositório por ambiente (URL, branch, `build_path`,
|
|
88
|
+
registry).
|
|
89
|
+
- [ ] Origin do ambiente com Talos no ar; agent (app + origin + path único no origin); worker (porta
|
|
90
|
+
livre no host, para service).
|
|
91
|
+
- [ ] Variáveis de ambiente do (app, ambiente) cadastradas — inclusive identidade no Argos, se usar
|
|
92
|
+
Orfeu.
|
|
93
|
+
- [ ] Domínio vinculado ao agent (sem domínio, o app cai no bloco coringa `:443` com certificado
|
|
94
|
+
interno autoassinado).
|
|
95
|
+
- [ ] Grupo do Hefesto ligado ao app para quem vai operar sem perfil de desenvolvedor/administrador.
|
|
96
|
+
|
|
97
|
+
## Armadilhas mais comuns (lista completa em `references/diagnostico.md`)
|
|
98
|
+
|
|
99
|
+
- **"Configuration 'x' is not set in the workspace"** no build de site: o ambiente do Hefesto tem
|
|
100
|
+
um nome que não existe no `angular.json`. O `CONFIGURATION` é o nome do ambiente, sem tradução.
|
|
101
|
+
- **502 só na rota do app**: worker cadastrado mas container parado/caindo, ou o processo escuta em
|
|
102
|
+
outra porta / em `127.0.0.1`.
|
|
103
|
+
- **404 em tudo do service, mas `/health` direto no container funciona**: o app responde na raiz e
|
|
104
|
+
o Caddy manda o path completo (`/meu-app/...`).
|
|
105
|
+
- **Mudou a variável e nada aconteceu**: variáveis só entram no próximo deploy/redeploy.
|
|
106
|
+
- **Deploy demora ~10 s a mais e some auditoria**: SIGTERM não chega ao processo (CMD em shell form
|
|
107
|
+
ou via `npm`).
|
|
108
|
+
- **"Essa versão não existe mais no registry"** no rollback: a retenção já apagou a tag.
|
|
109
|
+
- **Build passa local e falha no Ciclope**: depende de arquivo ignorado pelo git, de `.npmrc` local
|
|
110
|
+
ou de `node_modules` do contexto.
|
|
111
|
+
|
|
112
|
+
## Índice de referências
|
|
113
|
+
|
|
114
|
+
| Arquivo | Conteúdo |
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `references/conceitos.md` | Glossário: projeto, aplicação, tipos, repositório, conector, registry, origin, agent, worker, domínio, variáveis, grupos, tags, solicitação, histórico |
|
|
117
|
+
| `references/fluxo.md` | Deploy ponta a ponta (Ciclope, registry, Talos, Caddy), versões e retenção, redeploy, rollback, solicitações e seus estados |
|
|
118
|
+
| `references/preparar-app.md` | O que o app precisa ter: Dockerfile, porta, path, health, SIGTERM, variáveis, build args, site, réplicas e tarefas em background |
|
|
119
|
+
| `references/diagnostico.md` | Onde olhar (histórico, logs do container, Caddyfile), mensagens de erro do Hefesto e o que significam, erros comuns com causa |
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# Conceitos do Hefesto
|
|
2
|
+
|
|
3
|
+
Glossário na ordem em que as coisas são cadastradas. Os nomes entre crases são os da API/banco.
|
|
4
|
+
|
|
5
|
+
## Organização
|
|
6
|
+
|
|
7
|
+
### Projeto (`project`)
|
|
8
|
+
Só agrupa aplicações (ex.: o front, o gateway GraphQL e o backend de um mesmo produto). Não tem
|
|
9
|
+
configuração de deploy própria.
|
|
10
|
+
|
|
11
|
+
### Aplicação (`app`)
|
|
12
|
+
Uma unidade implantável: um Dockerfile, uma imagem.
|
|
13
|
+
|
|
14
|
+
| Campo | Significado |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| `app_name` | identificador técnico, **imutável**. Vira o nome da imagem no registry (`<registry>/<app_name>`) e a base do nome do container. Use minúsculas, dígitos e hífen. |
|
|
17
|
+
| `display_name` | nome de exibição, editável |
|
|
18
|
+
| tipo | `service` (roda um processo) ou `site` (arquivos estáticos servidos pelo Caddy) |
|
|
19
|
+
| `port` | porta em que o processo escuta **dentro** do container (só `service`) |
|
|
20
|
+
| `site_mode` | só `site`: `spa` (qualquer path não encontrado devolve `index.html`) ou `static` (file server puro) |
|
|
21
|
+
| `enabled` | desligar sem apagar |
|
|
22
|
+
|
|
23
|
+
Use `spa` para Angular com roteamento no cliente; `static` para documentação/HTML puro, onde um
|
|
24
|
+
path inexistente deve dar 404.
|
|
25
|
+
|
|
26
|
+
### Grupo (`group`) e acesso
|
|
27
|
+
Quem pode operar a aplicação. Usuários com o perfil (badge do Argos) de **Desenvolvedor** ou
|
|
28
|
+
**Administrador** veem e operam tudo. Os demais (ex.: **Operador**) só veem as aplicações ligadas a
|
|
29
|
+
um grupo do qual são membros, e a tela de operação não oferece rollback para eles. A checagem é
|
|
30
|
+
feita no servidor: submeter uma solicitação para app/agent/worker fora dos seus grupos dá 403.
|
|
31
|
+
|
|
32
|
+
### Tag (`tag`)
|
|
33
|
+
Rótulo livre para origins e containers (filtro/organização no inventário). Não confundir com a tag
|
|
34
|
+
da imagem Docker.
|
|
35
|
+
|
|
36
|
+
## Código e imagem
|
|
37
|
+
|
|
38
|
+
### Conector (`connector`)
|
|
39
|
+
Credencial de acesso a um provedor git (provedor, usuário, token). O token entra no clone como
|
|
40
|
+
header HTTP, fora da linha de comando e dos logs. Use um token **só de leitura**.
|
|
41
|
+
|
|
42
|
+
### Registry (`registry`)
|
|
43
|
+
Onde as imagens são publicadas e de onde os origins puxam. Tem URL, usuário/senha, `verify_ssl`
|
|
44
|
+
(desligar só para registry com certificado de CA interna que os hosts não conhecem) e, opcionalmente,
|
|
45
|
+
uma URL de gerenciamento para apagar tags na retenção. Um mesmo registry pode servir vários
|
|
46
|
+
ambientes (e até várias instalações do Hefesto): as tags levam o ambiente no nome.
|
|
47
|
+
|
|
48
|
+
### Repositório (`repository`) — um por (aplicação, ambiente)
|
|
49
|
+
| Campo | Significado |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| URL | repositório git (HTTPS) |
|
|
52
|
+
| branch | branch clonado para esse ambiente (ex.: `develop` em homol, `main` em prod) |
|
|
53
|
+
| `build_path` | subpasta usada como contexto do build (monorepo). Vazio = raiz. Não pode sair do repo. |
|
|
54
|
+
| conector | credencial do clone |
|
|
55
|
+
| registry | destino da imagem; sem ele não há build |
|
|
56
|
+
|
|
57
|
+
### Build (`build`)
|
|
58
|
+
Log das tentativas de build (status `building`/`built`/`failed`, quando). **A fonte da verdade do
|
|
59
|
+
que existe é o registry**: a lista de versões mostrada é reconciliada com as tags publicadas (uma
|
|
60
|
+
tag feita por outra ferramenta aparece com origem "registry"; uma linha `built` cuja tag sumiu é
|
|
61
|
+
removida).
|
|
62
|
+
|
|
63
|
+
## Infraestrutura
|
|
64
|
+
|
|
65
|
+
### Ambiente (`environment`)
|
|
66
|
+
`dev`, `homol`, `prod`... O **nome** importa em dois lugares:
|
|
67
|
+
- prefixo da tag da imagem (sanitizado: sem acento/espaço);
|
|
68
|
+
- `CONFIGURATION` do build de site, **sem sanitização** — precisa existir com esse nome exato no
|
|
69
|
+
`angular.json`.
|
|
70
|
+
|
|
71
|
+
### Origin (`origin`)
|
|
72
|
+
Um servidor com o **Talos** rodando (há também o tipo `kubernetes` no cadastro). Pertence a **um**
|
|
73
|
+
ambiente: tudo que roda nele é daquele ambiente. Tem a URL do agente, o token do agente, `verify_ssl`
|
|
74
|
+
e, opcionalmente, a URL de métricas. Cada origin tem **um Caddy**, gerenciado pelo Talos, que expõe
|
|
75
|
+
todos os apps daquele servidor.
|
|
76
|
+
|
|
77
|
+
### Agent (`agent`) — vínculo aplicação + origin + path
|
|
78
|
+
"Esta aplicação é publicada neste servidor, neste caminho."
|
|
79
|
+
- uma aplicação tem no máximo um agent por origin;
|
|
80
|
+
- o `path` é único por origin (dois apps não disputam `/api`);
|
|
81
|
+
- sem path = handler raiz do domínio (só um por domínio).
|
|
82
|
+
|
|
83
|
+
Não confundir com o Talos (o programa agente) nem com a credencial do agente.
|
|
84
|
+
|
|
85
|
+
### Worker (`worker`) — a execução de fato
|
|
86
|
+
- `service`: um container. Nome `<app_name>@<porta>` (no Podman vira `<app_name>-<porta>`), porta
|
|
87
|
+
publicada no host. Vários workers do mesmo agent = réplicas; o Caddy balanceia entre eles e tira da
|
|
88
|
+
rotação, por 30 s, o que falhar.
|
|
89
|
+
- `site`: sem container nem porta; os arquivos ficam num volume do Caddy, numa pasta por agent.
|
|
90
|
+
|
|
91
|
+
Guarda o estado do último deploy: `status` (`pending`, `deploying`, `running`, `failed`),
|
|
92
|
+
`running_image_tag`, `deployed_at`.
|
|
93
|
+
|
|
94
|
+
### Domínio (`domain`)
|
|
95
|
+
Nome de host atendido pelo Caddy de um ou mais origins. Os agents são vinculados aos domínios; cada
|
|
96
|
+
origin só serve os próprios agents. Agent **sem domínio vinculado** cai no bloco coringa `:443`
|
|
97
|
+
(qualquer Host), com certificado interno autoassinado gerado na hora. Os paths `/metrics` e
|
|
98
|
+
`/talos/*` desse bloco são reservados (métricas e API do agente) e têm prioridade.
|
|
99
|
+
|
|
100
|
+
### Variáveis de ambiente (`app_environment_vars`)
|
|
101
|
+
Chave/valor por (aplicação, ambiente), iguais em todos os origins daquele ambiente. Aplicadas como
|
|
102
|
+
um `--env-file` temporário (600, apagado logo depois) no `podman run` do próximo deploy, redeploy ou
|
|
103
|
+
rollback — o valor não passa pelo argv. Não valem para site (não
|
|
104
|
+
há processo; a configuração do site é decidida no build).
|
|
105
|
+
|
|
106
|
+
## Operação
|
|
107
|
+
|
|
108
|
+
### Solicitação (`requested`)
|
|
109
|
+
Pedido de operação feito por um usuário, instância de um **tipo** (`types`) cujo **fluxo** (`flow`)
|
|
110
|
+
é uma lista ordenada de **etapas** (`steps`). Tipos de deploy existentes:
|
|
111
|
+
|
|
112
|
+
| Tipo | Etapas |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| Deploy de Serviços / Deploy de Sites | Início → Build → Deploy → Fim |
|
|
115
|
+
| Redeploy de Serviços / Redeploy de Sites | Início → Deploy → Fim |
|
|
116
|
+
|
|
117
|
+
O dado da solicitação é o `app_id` + `agent_id` + `worker_id` (e, no Deploy, `repository_id` e a
|
|
118
|
+
parte da versão a incrementar). Status: Criada → Finalizada | Falhou | Cancelada. O fluxo é
|
|
119
|
+
configurável (etapas e posições), mas cada etapa precisa de uma função registrada no servidor:
|
|
120
|
+
etapa sem função faz a solicitação falhar, nunca ficar parada.
|
|
121
|
+
|
|
122
|
+
### Histórico (`execution`)
|
|
123
|
+
Uma linha por mudança de estado de cada etapa: `current` (aguardando) → `processing` → `success`
|
|
124
|
+
ou `error`, com a mensagem (no erro de build, o fim da saída do `podman build`). É o primeiro lugar
|
|
125
|
+
para diagnosticar. Mudanças são publicadas em tempo real para a UI.
|
|
126
|
+
|
|
127
|
+
### Deploy, Redeploy e Rollback
|
|
128
|
+
- **Deploy**: builda uma versão nova e implanta.
|
|
129
|
+
- **Redeploy**: implanta a versão mais recente já publicada, sem build (útil depois de mudar
|
|
130
|
+
variáveis ou para recriar um container).
|
|
131
|
+
- **Rollback**: implanta uma versão anterior escolhida na lista do registry daquele ambiente.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Logs e diagnóstico
|
|
2
|
+
|
|
3
|
+
## Onde olhar, em ordem
|
|
4
|
+
|
|
5
|
+
1. **Histórico da solicitação** (detalhe da solicitação): qual etapa falhou e a mensagem. No erro de
|
|
6
|
+
build a mensagem traz o fim da saída do `podman build` — o erro real do `npm`/`pip`/`ng` costuma
|
|
7
|
+
estar ali, não na primeira linha ("exit status 1" é só o resumo).
|
|
8
|
+
2. **Logs do container** (Origins → container → logs): últimas 200 linhas por padrão (até 5000),
|
|
9
|
+
com timestamp. É o stdout/stderr do processo principal.
|
|
10
|
+
3. **Status/estatísticas do container**: reiniciando em loop = processo morrendo na subida (config,
|
|
11
|
+
porta, dependência).
|
|
12
|
+
4. **Caddyfile do origin** (Origins → configuração do Caddy): confirma path, upstream
|
|
13
|
+
(`<app>-<porta>:<porta do app>`) e domínio que o Hefesto gerou.
|
|
14
|
+
5. **`/health` pelo domínio e pelo path**: separa "app quebrado" de "rota errada".
|
|
15
|
+
|
|
16
|
+
## Mensagens do Hefesto
|
|
17
|
+
|
|
18
|
+
| Mensagem | Causa | O que fazer |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| Este repositório não tem um registry configurado. | repositório do ambiente sem registry | cadastre o registry no repositório |
|
|
21
|
+
| Nenhum repositório configurado para esse ambiente. | worker num origin de um ambiente sem repositório | crie o repositório daquele ambiente |
|
|
22
|
+
| O repositório informado não corresponde ao ambiente do agente/worker escolhido. | escolheu o repositório de outro ambiente | use o repositório do ambiente do origin |
|
|
23
|
+
| Não foi possível consultar as versões no registry | registry fora/credencial errada/certificado | confira registry, usuário e `verify_ssl` |
|
|
24
|
+
| Nenhuma imagem buildada para esse ambiente ainda. | Redeploy antes do primeiro build | faça um Deploy (com build) |
|
|
25
|
+
| Essa versão não existe mais no registry. | rollback para tag apagada pela retenção | escolha outra versão; aumente a retenção se precisar de mais histórico |
|
|
26
|
+
| podman build excedeu Ns e foi cancelado | build lento ou travado | `timeout -k` nos passos do Dockerfile, cache de dependências, ordem dos COPY; o passo travado pode seguir rodando no host do Ciclope |
|
|
27
|
+
| git clone failed | token sem acesso, branch inexistente, URL errada | conector e branch do repositório |
|
|
28
|
+
| podman login failed | usuário/senha do registry | cadastro do registry |
|
|
29
|
+
| podman pull/run failed (na etapa Deploy) | origin sem acesso ao registry, porta do host ocupada, imagem sem o estágio certo | ver detalhe; porta → troque a do worker |
|
|
30
|
+
| podman cp ... /dist ... no such file | site buildado sem `/dist` na raiz | estágio `site` precisa de `COPY --from=build .../browser /dist` |
|
|
31
|
+
| nenhuma função registrada para este step | etapa adicionada ao fluxo sem implementação no servidor | remova a etapa do fluxo ou implemente |
|
|
32
|
+
| Você não tem acesso a esta aplicação. / Agente ou worker não pertencem à aplicação informada. | usuário sem grupo do app, ou ids misturados | vincule o grupo ao app |
|
|
33
|
+
|
|
34
|
+
## Sintomas comuns
|
|
35
|
+
|
|
36
|
+
| Sintoma | Causa provável | Por quê |
|
|
37
|
+
| --- | --- | --- |
|
|
38
|
+
| 502 só na rota do app | container parado/caindo; processo em outra porta; escuta em `127.0.0.1` | o Caddy encaminha para `<container>:<porta do app>`; nada ouvindo lá = 502 |
|
|
39
|
+
| 502 intermitente com 2+ workers | um worker fora, requisição caindo nele antes de sair da rotação | o Caddy tenta o próximo por até 5 s e tira o falho por 30 s; se for sempre, conserte o worker |
|
|
40
|
+
| 404 em toda a API, `/health` interno OK | app responde na raiz | o path do agent chega completo; configure o prefixo no app |
|
|
41
|
+
| `/meu-app` funciona mas `/meu-app-x` cai no app errado | prefixos parecidos | `path /p /p/*` não casa `/p-x`; confira se não há outro agent com path na raiz pegando a requisição |
|
|
42
|
+
| Rota do app responde com outro app | dois agents sem path no mesmo domínio | só um handler raiz por domínio; o segundo é ignorado |
|
|
43
|
+
| Site: tela branca, assets 404 | `baseHref` diferente do path do agent | o Caddy remove o prefixo, mas o navegador pede os assets com o `baseHref` do build |
|
|
44
|
+
| Site: F5 numa rota dá 404 | `site_mode = static` | use `spa` para fallback no `index.html` |
|
|
45
|
+
| Site: build falha com "Configuration 'x' is not set" | nome do ambiente sem configuração no `angular.json` | `CONFIGURATION` = nome do ambiente, exato |
|
|
46
|
+
| Site antigo depois do deploy | cache do navegador no `index.html` | arquivos com hash podem ter cache longo; `index.html` não |
|
|
47
|
+
| Container reinicia em loop | variável obrigatória faltando, dependência inacessível na subida, erro de import | logs do container mostram o erro da primeira linha de settings |
|
|
48
|
+
| Variável nova não aparece | variáveis só entram no `run` | faça Redeploy |
|
|
49
|
+
| Deploy "concluído" mas app fora | o Talos não espera health | sempre confira logs e `/health` depois |
|
|
50
|
+
| Cada deploy demora 10 s a mais; auditoria perdida | SIGTERM não chega ao processo | CMD em forma exec, app trata SIGTERM (ver **docker**) |
|
|
51
|
+
| Job/coleta executando em dobro | mais de um worker (ou `--workers`) com agendador no lifespan | separe o papel ou use lock (ver `preparar-app.md`) |
|
|
52
|
+
| Build lento sempre do zero | `COPY . .` antes do install, ARG antes do install, contexto com `node_modules`/`.git` | ver **docker** |
|
|
53
|
+
| Build passa local, falha no Ciclope | arquivo não versionado, `.npmrc` local, lockfile desatualizado (`npm ci` exige lockfile em sincronia) | builde a partir de um clone limpo |
|
|
54
|
+
| Login do Orfeu falha só atrás do bloco coringa | certificado interno autoassinado do `:443` | vincule um domínio com certificado válido; em último caso, desligue a verificação TLS do autorizador só nesse ambiente |
|
|
55
|
+
| Página trava em HTTP puro por IP | PKCE usa `crypto.subtle`, que só existe em HTTPS/localhost | acesse por HTTPS (o bloco coringa já é `:443`) |
|
|
56
|
+
| App em `/metrics` ou `/talos` não responde | paths reservados do Caddy do origin | escolha outro path |
|
|
57
|
+
| Porta do worker recusada | outra coisa já usa a porta no host, ou outro worker do mesmo agent | escolha porta livre (é única por agent e no host) |
|
|
58
|
+
|
|
59
|
+
## Reproduzir o build como o Ciclope
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git clone --depth 1 --single-branch --branch <branch> <url> /tmp/x && cd /tmp/x/<build_path>
|
|
63
|
+
podman build -t teste . # service
|
|
64
|
+
podman build --target site --build-arg CONFIGURATION=homol -t teste . # site
|
|
65
|
+
podman run --rm --env-file .env.teste -p 8080:<porta do app> teste # service: confira /health
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
O `.env.teste` é local (fora do repo e com permissão restrita); segredo em `-e` fica no histórico do
|
|
69
|
+
shell. Com Docker local funciona igual para a maioria dos casos; diferenças do Podman/Buildah estão na
|
|
70
|
+
skill **docker**.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Fluxo de deploy ponta a ponta
|
|
2
|
+
|
|
3
|
+
## Visão geral
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
solicitação (UI) registry
|
|
7
|
+
usuário ───────────────▶ Hefesto ──build──▶ Ciclope ──push──▶ <app>:<amb>-x.y.z.w
|
|
8
|
+
│ │
|
|
9
|
+
└──deploy──▶ Talos (origin do ambiente) ◀─┘ pull
|
|
10
|
+
│
|
|
11
|
+
├─ service: podman run ─┐
|
|
12
|
+
├─ site: /dist → volume ├─▶ Caddy do origin ─▶ usuários
|
|
13
|
+
└─ Caddyfile (do Hefesto)┘
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## 1. Início (validação)
|
|
17
|
+
|
|
18
|
+
- app, agent e worker existem e pertencem um ao outro;
|
|
19
|
+
- no Deploy: o repositório escolhido é o **do ambiente do origin** do worker. Sem essa checagem daria
|
|
20
|
+
para buildar a imagem de `homol` e o passo Deploy pegar a última de `prod`;
|
|
21
|
+
- sanidade (só aviso em log): tipo da solicitação (Sites/Serviços) bate com o tipo do app. Quem decide
|
|
22
|
+
o comportamento é sempre o tipo do app.
|
|
23
|
+
|
|
24
|
+
## 2. Build (Ciclope)
|
|
25
|
+
|
|
26
|
+
1. **Versão**: o Hefesto lista as tags do app no registry, filtra as do ambiente
|
|
27
|
+
(`<ambiente>-x.y.z.w`), pega a maior (somando builds em andamento) e incrementa a parte escolhida
|
|
28
|
+
(`major`, `minor`, `fix`, `test`), zerando as menores: `1.2.3.4` + minor = `1.3.0.0`. Sem versão
|
|
29
|
+
anterior parte de `0.0.0.0`. Registry fora do ar = o build não começa (chutar a versão causaria
|
|
30
|
+
colisão com outra instalação que compartilha o registry).
|
|
31
|
+
2. **Clone**: branch do repositório, `--depth 1 --single-branch --no-tags`, credencial do conector
|
|
32
|
+
em header (não aparece em `ps` nem em log; saídas de erro passam por redação de credenciais).
|
|
33
|
+
3. **Build**: `podman build` (Buildah, não Docker) com `--jobs 2` (estágios independentes em
|
|
34
|
+
paralelo), no `build_path`. Para site: `--target site --build-arg CONFIGURATION=<ambiente>`.
|
|
35
|
+
Limite padrão de 900 s; estourou = 504 com as últimas linhas da saída.
|
|
36
|
+
4. **Push** para `<registry>/<app_name>:<ambiente>-<versão>`.
|
|
37
|
+
5. **Retenção** (best-effort, nunca derruba o build): apaga as tags do ambiente além das N mais
|
|
38
|
+
novas (padrão 5), **exceto** as que algum worker está rodando. Tags de outros ambientes nunca são
|
|
39
|
+
tocadas.
|
|
40
|
+
|
|
41
|
+
O cache do build fica no host do Ciclope (camadas + `--mount=type=cache`); imagens sem tag só são
|
|
42
|
+
limpas depois de dias, para não perder o cache de quem builda com frequência. Por isso a ordem dos
|
|
43
|
+
`COPY` no Dockerfile faz diferença real no tempo de build (ver **docker**).
|
|
44
|
+
|
|
45
|
+
> O Podman só cancela um build no **próximo** passo do Dockerfile. Um `npm ci` ou `ng build` travado
|
|
46
|
+
> continua rodando no host mesmo depois do timeout do Ciclope — por isso os passos longos levam
|
|
47
|
+
> `timeout -k` no próprio Dockerfile.
|
|
48
|
+
|
|
49
|
+
## 3. Deploy (Talos)
|
|
50
|
+
|
|
51
|
+
O Hefesto resolve a **versão mais nova publicada** para o ambiente do origin e chama o Talos daquele
|
|
52
|
+
origin.
|
|
53
|
+
|
|
54
|
+
### service
|
|
55
|
+
1. `podman login` + `pull` da imagem;
|
|
56
|
+
2. `podman stop` do container atual (SIGTERM, 10 s, depois SIGKILL) e `rm`;
|
|
57
|
+
3. `podman run -d --name <app>-<porta> -p <porta do worker>:<porta do app> --restart unless-stopped
|
|
58
|
+
--network <rede do origin> --env-file <arquivo temporário> <imagem>`; as variáveis do (app,
|
|
59
|
+
ambiente) vão num arquivo com permissão 600, apagado assim que o `run` termina — nunca como `-e K=V`
|
|
60
|
+
no argv, onde apareceriam em `ps` no host e no log de comandos;
|
|
61
|
+
4. worker vira `running` com a tag; o Hefesto regenera o Caddyfile do origin e o Talos recarrega o
|
|
62
|
+
Caddy.
|
|
63
|
+
|
|
64
|
+
Consequências:
|
|
65
|
+
- há uma janela de indisponibilidade entre o stop e o processo novo ficar pronto (um worker só). Com
|
|
66
|
+
dois ou mais workers, faça o deploy **um de cada vez**: o Caddy tira da rotação o que estiver fora;
|
|
67
|
+
- `running` = container criado. Se o processo cair logo depois, o `--restart` fica reiniciando e o
|
|
68
|
+
Hefesto não percebe: confira os logs e o `/health`;
|
|
69
|
+
- a rede do origin permite que o app alcance outros serviços daquele servidor pelo nome do container.
|
|
70
|
+
|
|
71
|
+
### site
|
|
72
|
+
1. `pull`, `podman create` (o container nunca roda — por isso o `CMD ["unused"]` no estágio `site`);
|
|
73
|
+
2. esvazia a pasta do agent no volume do Caddy e copia `/dist/.` da imagem para lá;
|
|
74
|
+
3. Caddyfile regenerado: `file_server` na pasta, `uri strip_prefix <path>`, e `try_files {path}
|
|
75
|
+
/index.html` se `site_mode = spa`.
|
|
76
|
+
|
|
77
|
+
### Caddyfile
|
|
78
|
+
Gerado inteiro a cada mudança (agent, domínio, vínculo, deploy, remoção), um bloco por domínio:
|
|
79
|
+
- service: `@app path /p /p/*` → `reverse_proxy <app>-<porta>:<porta do app>` para **todos os
|
|
80
|
+
workers cadastrados** (worker parado = 502 só na rota dele, nunca derruba as outras);
|
|
81
|
+
- paths ordenados do mais longo para o mais curto (`/x/graphql` antes de `/x`);
|
|
82
|
+
- `/p` sem barra também casa;
|
|
83
|
+
- `encode gzip` em todos os blocos.
|
|
84
|
+
|
|
85
|
+
Falha ao sincronizar o Caddy não falha o deploy (o próximo evento tenta de novo).
|
|
86
|
+
|
|
87
|
+
## 4. Fim
|
|
88
|
+
|
|
89
|
+
Marca a solicitação como Finalizada. Em qualquer etapa com erro: execução `error` com a mensagem e
|
|
90
|
+
solicitação Falhou. Uma solicitação parada pode ser **avançada** de novo: retoma da etapa que falhou
|
|
91
|
+
(ou da seguinte, se a última deu certo).
|
|
92
|
+
|
|
93
|
+
## Redeploy
|
|
94
|
+
|
|
95
|
+
Mesmo passo 3 sem passar pelo build: implanta a última versão publicada do ambiente. Use para:
|
|
96
|
+
- aplicar variáveis de ambiente alteradas;
|
|
97
|
+
- recriar um container que alguém parou ou removeu à mão;
|
|
98
|
+
- publicar em um worker novo uma versão que já existe.
|
|
99
|
+
|
|
100
|
+
## Rollback
|
|
101
|
+
|
|
102
|
+
Escolha a versão na lista de builds do ambiente (vem do registry) e o Hefesto roda o passo 3 com
|
|
103
|
+
ela. Regras:
|
|
104
|
+
- só versões que ainda existem no registry; a retenção apaga as antigas, menos as que estão rodando;
|
|
105
|
+
- variáveis de ambiente são as **atuais**, não as da época da versão. Se a versão antiga precisa de
|
|
106
|
+
uma variável que foi removida/renomeada, ajuste antes;
|
|
107
|
+
- migrations de banco **não** voltam. Versão antiga contra schema novo precisa ser compatível
|
|
108
|
+
(migrations aditivas, nunca destrutivas no mesmo release);
|
|
109
|
+
- site: o `/dist` da versão escolhida substitui o atual.
|
|
110
|
+
- No perfil Operador a tela não oferece rollback.
|
|
111
|
+
|
|
112
|
+
## Versões: qual parte incrementar
|
|
113
|
+
|
|
114
|
+
| Parte | Quando |
|
|
115
|
+
| --- | --- |
|
|
116
|
+
| `major` | quebra de contrato (API, schema incompatível) |
|
|
117
|
+
| `minor` | funcionalidade nova compatível |
|
|
118
|
+
| `fix` | correção |
|
|
119
|
+
| `test` | build de teste/validação em ambiente não produtivo |
|
|
120
|
+
|
|
121
|
+
A numeração é por ambiente: `homol-1.3.0.0` e `prod-1.3.0.0` são builds diferentes (branch e
|
|
122
|
+
`CONFIGURATION` de cada ambiente). Promover para produção = novo build no repositório de prod.
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Preparar um app para o Hefesto
|
|
2
|
+
|
|
3
|
+
O Hefesto não tem manifesto próprio: o contrato é o **Dockerfile + o cadastro**. Como escrever o
|
|
4
|
+
Dockerfile está na skill **docker**; aqui fica o que o Hefesto espera dele e do processo.
|
|
5
|
+
|
|
6
|
+
## Repositório
|
|
7
|
+
|
|
8
|
+
- Dockerfile e `.dockerignore` na raiz do contexto (raiz do repo ou `build_path`). O Podman só lê o
|
|
9
|
+
`.dockerignore` da raiz do contexto.
|
|
10
|
+
- Tudo que o build precisa está **versionado**: lockfile (`package-lock.json`, `requirements.txt`
|
|
11
|
+
com versões fixas), configs, assets. O clone é raso e limpo.
|
|
12
|
+
- Dependências vêm de registries públicos (npm, PyPI) — `@trismegisto/*`, `@orfeu/*` e `orfeu`
|
|
13
|
+
inclusive. Sem `.npmrc`/`pip.conf` com credencial no repo ou na imagem.
|
|
14
|
+
- Script `.sh` (entrypoint, build) com fim de linha LF garantido pelo `.gitattributes` (`*.sh text eol=lf`):
|
|
15
|
+
clonado com CRLF de uma máquina Windows, ele quebra no container com `$'\r': command not found`.
|
|
16
|
+
|
|
17
|
+
## Build args
|
|
18
|
+
|
|
19
|
+
| Arg | Quem manda | Uso |
|
|
20
|
+
| --- | --- | --- |
|
|
21
|
+
| `CONFIGURATION` | Hefesto, só para `site` | nome do ambiente → `ng build --configuration $CONFIGURATION` |
|
|
22
|
+
|
|
23
|
+
- Declare o `ARG` **depois** da instalação de dependências (um ARG entra no ambiente de todos os
|
|
24
|
+
`RUN` seguintes; declarado antes, cada ambiente invalida o cache do `npm ci`).
|
|
25
|
+
- O Hefesto pode repassar outros build args que o Dockerfile não declara; ARG não declarado é
|
|
26
|
+
ignorado (só aviso). Não declare ARG para credencial: o valor fica no histórico da imagem.
|
|
27
|
+
- Nada de URL de serviço ou segredo em build arg de service: isso é configuração de **runtime**.
|
|
28
|
+
|
|
29
|
+
## Service (container)
|
|
30
|
+
|
|
31
|
+
| Requisito | Por quê |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| escuta em `0.0.0.0:<porta do cadastro>` | o Caddy chega pelo nome do container na rede do origin; `127.0.0.1` só aceita conexões de dentro do container |
|
|
34
|
+
| `ENV PORT=<mesma porta>` no Dockerfile e `EXPOSE` | o Hefesto não injeta `PORT`; o `EXPOSE` documenta |
|
|
35
|
+
| responde sob o **path do agent** | o Caddy repassa o path completo (`/meu-app/api/x`), sem strip |
|
|
36
|
+
| `GET <prefixo>/health` | diagnóstico pós-deploy e balanceamento; `200` só com as dependências reais OK, `503` caso contrário |
|
|
37
|
+
| CMD em forma exec, processo trata SIGTERM | `podman stop` dá 10 s; flush da auditoria do Orfeu, fechar conexões |
|
|
38
|
+
| config validada na subida, falha rápida | variável faltando derruba o processo com mensagem clara no log, não um erro na primeira requisição |
|
|
39
|
+
| logs em stdout/stderr, uma linha por evento | é o que o Talos mostra (`podman logs`); arquivo de log dentro do container some no próximo deploy |
|
|
40
|
+
| sem estado em disco local | o container é recriado a cada deploy; upload/arquivo vai para storage externo ou volume dedicado |
|
|
41
|
+
|
|
42
|
+
Prefixo por variável, com o padrão de cada stack:
|
|
43
|
+
|
|
44
|
+
| Stack | Como |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| Express/Apollo | `API_PREFIX` / caminho do `app.use(prefix, router)` e do `path` do Apollo (ver **express**, **apollo**) |
|
|
47
|
+
| FastAPI | `root_path` ou `APIRouter(prefix=...)` vindo de settings (ver **fastapi**) |
|
|
48
|
+
| SPA servida pelo próprio Node | base path da UI (`UI_BASE_PATH`) igual ao `baseHref` do build |
|
|
49
|
+
|
|
50
|
+
### Variáveis de ambiente
|
|
51
|
+
|
|
52
|
+
Cadastre no Hefesto, por ambiente, tudo que o app lê do ambiente: banco, Redis, URLs de outros
|
|
53
|
+
serviços, identidade no Argos (realm e app — ver **orfeu**), nível de log, `APP_ENV`/`NODE_ENV`.
|
|
54
|
+
|
|
55
|
+
- Os arquivos `.env.<ambiente>` do repo são para rodar local; a imagem não os leva. Se o app carrega
|
|
56
|
+
`.env.<APP_ENV>` com `load_dotenv`, o arquivo não existe no container e o valor tem que vir do
|
|
57
|
+
ambiente — o loader não reclama, a validação de settings é que acusa.
|
|
58
|
+
- Segredo só no cadastro de variáveis (ou no gerenciador de segredos do servidor), nunca no repo,
|
|
59
|
+
nunca em `ENV` do Dockerfile — **nem como valor padrão** (`ENV AGENT_TOKEN=changeme`,
|
|
60
|
+
`getenv("TOKEN", "changeme")`). Sem o cadastro, o app tem que **cair na subida** dizendo qual variável
|
|
61
|
+
falta; com default, ele sobe aceitando um segredo que está no repositório
|
|
62
|
+
(skill **docker** em `references/porques.md`).
|
|
63
|
+
- Alterou? **Redeploy.**
|
|
64
|
+
|
|
65
|
+
### Réplicas e tarefas em background
|
|
66
|
+
|
|
67
|
+
Cada worker é um container inteiro, com lifespan próprio. Agendadores, coletores, consumidores de
|
|
68
|
+
fila e "tarefa a cada N segundos" no startup rodam **uma vez por worker** (e uma vez por processo,
|
|
69
|
+
se o servidor tiver vários processos — `uvicorn --workers`, cluster do Node).
|
|
70
|
+
|
|
71
|
+
Escolha uma:
|
|
72
|
+
1. **Separar o papel**: variável `APP_ROLE=api|worker` (ou `collector`); o worker de API pode ter
|
|
73
|
+
réplicas, o de tarefas tem exatamente uma. Pode ser o mesmo app com dois agents/workers e
|
|
74
|
+
variáveis diferentes, ou dois apps a partir da mesma imagem.
|
|
75
|
+
2. **Lock distribuído** (Redis `SET NX PX`, advisory lock do Postgres) em cada ciclo: só quem pegou o
|
|
76
|
+
lock executa.
|
|
77
|
+
3. Um worker só, sem `--workers` > 1 no processo (aceitável quando não há carga).
|
|
78
|
+
|
|
79
|
+
Ver também **fastapi** (`references/integracoes.md`) para o padrão em Python.
|
|
80
|
+
|
|
81
|
+
### Banco e migrations
|
|
82
|
+
|
|
83
|
+
O Hefesto não roda migration. Aplique fora do boot (pipeline ou passo manual) e mantenha cada release
|
|
84
|
+
compatível com o schema da versão anterior — é o que permite rollback.
|
|
85
|
+
|
|
86
|
+
## Site (estático)
|
|
87
|
+
|
|
88
|
+
- Estágio `site` (nome exato) `FROM scratch`, com o build em **`/dist`** e `CMD ["unused"]`.
|
|
89
|
+
- Uma configuração no `angular.json` **para cada nome de ambiente** do Hefesto, com:
|
|
90
|
+
- `baseHref` = path do agent (com barra final: `/meu-app/`); agent na raiz = `/`;
|
|
91
|
+
- endpoints do ambiente (`environment.<amb>.ts`) — o site não recebe variável de runtime.
|
|
92
|
+
- `site_mode = spa` para app com rotas no cliente (deep link e F5 funcionam); `static` só para HTML
|
|
93
|
+
puro.
|
|
94
|
+
- Mesmo build servindo dois paths diferentes não funciona: `baseHref` é fixado no build.
|
|
95
|
+
- Detalhes do build e budgets: **angular** (`references/testes-build.md`).
|
|
96
|
+
|
|
97
|
+
## Cadastro (resumo)
|
|
98
|
+
|
|
99
|
+
1. Projeto → Aplicação (tipo, `app_name`, porta ou modo do site).
|
|
100
|
+
2. Repositório por ambiente (conector, URL, branch, `build_path`, registry).
|
|
101
|
+
3. Agent por origin (path), workers (porta livre do host, para service).
|
|
102
|
+
4. Variáveis por ambiente.
|
|
103
|
+
5. Domínio vinculado ao agent.
|
|
104
|
+
6. Grupo, se operadores vão usar.
|
|
105
|
+
7. Solicitação **Deploy** escolhendo worker e parte da versão.
|