@acropole/skills 1.2.0 → 1.4.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 +4 -3
- package/package.json +4 -4
- package/skills/acropole/SKILL.md +2 -0
- package/skills/acropole/references/arquitetura.md +29 -5
- package/skills/acropole/references/fluxos/app-novo.md +4 -4
- package/skills/acropole/references/fluxos/tela-nova.md +1 -1
- package/skills/apollo/references/subscriptions.md +10 -4
- package/skills/apollo/references/testes-build.md +1 -0
- package/skills/auto-servico/SKILL.md +153 -0
- package/skills/auto-servico/references/diagnostico.md +42 -0
- package/skills/auto-servico/references/roteiros.md +63 -0
- package/skills/auto-servico/references/tools.md +108 -0
- package/skills/docker/SKILL.md +3 -0
- package/skills/docker/references/podman-local.md +73 -0
- package/skills/express/references/dados.md +3 -1
- package/skills/fastapi/SKILL.md +4 -4
- package/skills/fastapi/references/banco.md +53 -50
- package/skills/fastapi/references/estrutura.md +2 -2
- package/skills/fastapi/references/integracoes.md +8 -0
- package/skills/hefesto/SKILL.md +49 -14
- package/skills/hefesto/references/diagnostico.md +15 -5
- package/skills/hefesto/references/fluxo.md +64 -35
- package/skills/hefesto/references/mcp-diagnostico.md +44 -0
- package/skills/hefesto/references/mcp-roteiros.md +53 -0
- package/skills/hefesto/references/mcp-tools.md +94 -0
- package/skills/orfeu/SKILL.md +1 -1
- package/skills/orfeu/references/diferencas.md +1 -1
- package/skills/orfeu/references/node.md +1 -1
- package/skills/orquestracao/SKILL.md +1 -1
- package/skills/orquestracao/templates/spec.md +1 -1
- package/skills/trismegisto/SKILL.md +4 -4
- package/skills/trismegisto/references/angular-api.md +653 -507
- package/skills/trismegisto/references/angular-exports.md +541 -130
- package/skills/trismegisto/references/angular-types.md +1 -1
- package/skills/trismegisto/references/angular.md +28 -8
- package/skills/trismegisto/references/catalogo/icones.json +5 -0
- package/skills/trismegisto/references/catalogo/seletores.json +452 -31
- package/skills/trismegisto/references/catalogo/tokens.json +136 -16
- package/skills/trismegisto/references/spine-api.md +181 -44
- package/skills/trismegisto/references/spine-recipes.md +1 -1
- package/skills/trismegisto/references/spine.md +4 -3
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# Podman local no Windows (Podman Machine sobre WSL)
|
|
2
|
+
|
|
3
|
+
Como subir as stacks (Argos, Hefesto, workers) numa máquina Windows com Podman, e o que quebra no caminho. Tudo
|
|
4
|
+
aqui foi encontrado subindo a plataforma inteira do zero; cada item tem o sintoma para achar pela mensagem de erro.
|
|
5
|
+
|
|
6
|
+
## Máquina
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
podman machine init --cpus 4 --memory 6144 --now
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
- **Rootless** (o padrão). No rootful sobre WSL as portas publicadas não chegam ao Windows: o rootful publica por
|
|
13
|
+
NAT, sem socket ouvindo, e o encaminhamento do WSL só enxerga sockets. A rede em modo usuário
|
|
14
|
+
(`--user-mode-networking`) também não resolveu, e ligar e desligar essa opção apagou o `/etc/resolv.conf` da VM
|
|
15
|
+
(resolvido com `wsl --shutdown` e `podman machine start`).
|
|
16
|
+
- **Controlador `pids`**: a VM do WSL não o delega aos containers. Sem ajuste, **todo** container falha com
|
|
17
|
+
`crun: controller 'pids' is not available`. Desligue o limite nos dois lados, porque o cliente do Windows manda o
|
|
18
|
+
limite padrão no pedido, e reinicie a máquina para o serviço da API reler a configuração:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Windows: %APPDATA%\containers\containers.conf.d\50-pids.conf
|
|
22
|
+
# VM: /etc/containers/containers.conf.d/50-pids.conf (podman machine ssh + sudo)
|
|
23
|
+
[containers]
|
|
24
|
+
pids_limit = 0 # -1 não funciona; tem que ser 0
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- **Portas baixas** (o Caddy do Talos usa 80/443): `net.ipv4.ip_unprivileged_port_start=80` em
|
|
28
|
+
`/etc/sysctl.d/` dentro da VM.
|
|
29
|
+
- **Socket do Podman** para quem dispara containers (ciclope, talos): `/run/user/1000/podman/podman.sock`
|
|
30
|
+
(confirme o uid com `id -u` na VM).
|
|
31
|
+
|
|
32
|
+
## Compose
|
|
33
|
+
|
|
34
|
+
- **Rode o compose de dentro da VM** quando ele monta caminho absoluto (o socket no ciclope e no talos, o
|
|
35
|
+
`/etc/hostname`). O cliente do Windows trata `/run/...` como caminho do Windows (vira `/mnt/c/run/...`), e o socket
|
|
36
|
+
montado aparece no container como **pasta vazia** (`connection refused`). O repositório fica acessível na VM em
|
|
37
|
+
`/mnt/c/Users/...`:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
podman machine ssh "sudo dnf -y install podman-compose"
|
|
41
|
+
podman machine ssh "cd '/mnt/c/Users/<você>/.../apps/hefesto/compose' && podman-compose --in-pod false up -d"
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
- **`--in-pod false`** no podman-compose. O padrão agrupa os serviços num pod, e criar o cgroup do pod falha nessa
|
|
45
|
+
VM (`unable to create pod cgroup ... was already loaded or has a fragment file`).
|
|
46
|
+
- O `podman machine ssh` no Windows grava a chave do host num arquivo **`NUL`** no diretório atual (bug do Podman).
|
|
47
|
+
Não commite: apague pelo caminho exato (`rm -- caminho/NUL`), porque `find` não lista nomes reservados.
|
|
48
|
+
- O Git Bash converte argumentos que começam com `/` em caminho do Windows (`-w /srv` vira `C:/Program Files/Git/srv`).
|
|
49
|
+
Use `MSYS_NO_PATHCONV=1` nesses comandos.
|
|
50
|
+
|
|
51
|
+
## Rede e DNS
|
|
52
|
+
|
|
53
|
+
- Do container para um serviço publicado no host: `host.containers.internal` (o equivalente do
|
|
54
|
+
`host.docker.internal`).
|
|
55
|
+
- Um nome que precisa resolver **tanto nos containers quanto no engine** (ex.: o registry, usado no push e no
|
|
56
|
+
pull pelo engine e na API pelo hefesto-server): conecte o container do registry à rede do compose e, na VM, aponte
|
|
57
|
+
o nome para `127.0.0.1` no `/etc/hosts`. Nesse caso, impeça os containers de herdarem o `/etc/hosts` da VM, senão
|
|
58
|
+
o nome resolve para `127.0.0.1` também dentro deles:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
# VM: /etc/containers/containers.conf.d/60-hosts.conf
|
|
62
|
+
[containers]
|
|
63
|
+
base_hosts_file = "none"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- Cookies `Secure` (SSO do Argos) funcionam em `http://localhost` no navegador, que trata localhost como contexto
|
|
67
|
+
seguro. Em script (requests, curl), é preciso reenviá-los à mão.
|
|
68
|
+
|
|
69
|
+
## Contexto das aplicações
|
|
70
|
+
|
|
71
|
+
Também no compose local, cada serviço fica no próprio contexto (`/hefesto/server`, `/argos/...`): defina o
|
|
72
|
+
`API_PREFIX` do serviço e use o mesmo caminho nas URLs internas. Ver a regra em
|
|
73
|
+
`../../acropole/references/arquitetura.md` (seção 3).
|
|
@@ -151,7 +151,9 @@ Padrão adotado (genérico):
|
|
|
151
151
|
## Cache
|
|
152
152
|
|
|
153
153
|
Redis (`ioredis`) num módulo singleton iniciado antes do servidor; usado para rate limit, sessões
|
|
154
|
-
curtas e pub/sub.
|
|
154
|
+
curtas e pub/sub. Toda conexão é nomeada (obrigatório, acropole `arquitetura.md` §3.1): `connectionName:
|
|
155
|
+
process.env.REDIS_CLIENT_NAME?.trim() || '<app>-<componente>'` em todos os modos (standalone, Sentinel, e
|
|
156
|
+
`redisOptions` no Cluster), e a conexão de assinante (`duplicate()`) com o papel sufixado (`-subscriber`). Cache em memória com TTL curto (ex.: 30 s) é aceitável para listas pequenas lidas a
|
|
155
157
|
cada requisição (allowlist de CORS), sabendo que cada réplica tem o seu.
|
|
156
158
|
|
|
157
159
|
## Chamadas a outros serviços
|
package/skills/fastapi/SKILL.md
CHANGED
|
@@ -42,9 +42,9 @@ orfeu — não duplique aqui.
|
|
|
42
42
|
`SessionLocal` em `app.state`, sessão por requisição via `Depends(get_db)`. Rotas que usam a sessão
|
|
43
43
|
síncrona devem ser `def` (rodam no threadpool), não `async def`. Ver
|
|
44
44
|
[references/banco.md](references/banco.md).
|
|
45
|
-
9. **Schema do banco fora do
|
|
46
|
-
|
|
47
|
-
|
|
45
|
+
9. **Schema do banco fora do serviço, com Alembic**: pasta `database/` irmã do serviço, migrations em SQL em
|
|
46
|
+
`migrations/versions/NNNN_*.py` (`poe nova`, `poe migrate <ambiente>`), seed de ambiente em `seed/` e
|
|
47
|
+
`bootstrap.py` para role+database. O serviço não migra nada e não há `create_all` em produção.
|
|
48
48
|
10. **Configuração por ambiente**: `pydantic-settings` + `src/.env` (só `APP_ENV`) +
|
|
49
49
|
`src/settings/environment/.env.<APP_ENV>`; variáveis do processo vencem os arquivos. Nunca versione
|
|
50
50
|
valores reais; mantenha um `.env.example` só com nomes.
|
|
@@ -119,7 +119,7 @@ def create_tag(body: TagCreate, db: Session = Depends(get_db)):
|
|
|
119
119
|
|---|---|
|
|
120
120
|
| [references/estrutura.md](references/estrutura.md) | Árvore do projeto, responsabilidades por camada, `main.py`, settings/env (nomes), dependências |
|
|
121
121
|
| [references/rotas-erros.md](references/rotas-erros.md) | Convenção de rotas e ids, `@operation`, Pydantic (entrada/saída, camelCase), envelope, erros e status |
|
|
122
|
-
| [references/banco.md](references/banco.md) | Engine/sessão, models e schemas do Postgres, transações, SQL cru, `database/` com
|
|
122
|
+
| [references/banco.md](references/banco.md) | Engine/sessão, models e schemas do Postgres, transações, SQL cru, `database/` com Alembic (migrations, seed, ambientes), armadilhas |
|
|
123
123
|
| [references/integracoes.md](references/integracoes.md) | Clientes HTTP, `orfeu_headers`, token de app, Redis, tarefas em segundo plano, collectors, logs |
|
|
124
124
|
| [references/testes-deploy.md](references/testes-deploy.md) | pytest (SQLite em memória, Postgres com savepoint, fakes do Orfeu), Dockerfile, uvicorn, `.dockerignore` |
|
|
125
125
|
|
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
- **Postgres apenas.** O ramo MSSQL (`mssql+pyodbc`, ODBC driver na imagem) foi removido de todos os
|
|
6
6
|
serviços; não reintroduza sem consumidor real.
|
|
7
7
|
- **SQLAlchemy 2.x síncrono** + **`psycopg2-binary`** (`postgresql+psycopg2`). Sem asyncpg, sem ORM async.
|
|
8
|
-
- **
|
|
9
|
-
|
|
8
|
+
- **Schema versionado com Alembic numa pasta `database/` irmã do serviço** (abaixo), com migrations em SQL, e
|
|
9
|
+
nunca `create_all` em produção: `create_all` só nos testes (SQLite). O serviço não roda migration nenhuma.
|
|
10
10
|
- Um *schema* Postgres por área do projeto (`deploy`, `requests`, `catalogo`...), não `public`.
|
|
11
11
|
|
|
12
12
|
## Engine e sessão (`core/connections/database/events.py`)
|
|
@@ -81,8 +81,8 @@ class Tag(CatalogoBase):
|
|
|
81
81
|
|
|
82
82
|
- PK `UUID` chamada `<entidade>_id`; `TIMESTAMPTZ` (`DateTime(timezone=True)`); `TEXT` em vez de
|
|
83
83
|
`VARCHAR(n)` salvo regra real.
|
|
84
|
-
- O model espelha o
|
|
85
|
-
|
|
84
|
+
- O model espelha o schema das migrations de `database/migrations/versions/` — o SQL é a fonte da verdade; a
|
|
85
|
+
migration que muda uma tabela vem no mesmo PR que muda o model.
|
|
86
86
|
- Desativação lógica (`active=false`) quando há FK apontando, em vez de apagar.
|
|
87
87
|
- Constante do schema exportada (`CATALOGO_SCHEMA`) para os testes usarem `schema_translate_map`.
|
|
88
88
|
|
|
@@ -130,68 +130,71 @@ execução aborta num script que nem tem parâmetros. Soluções:
|
|
|
130
130
|
especial do psycopg2 e precisa de `%%`);
|
|
131
131
|
- query com parâmetros e um `:` literal: escape só esse (`'10\:30'`) ou passe o literal como parâmetro.
|
|
132
132
|
|
|
133
|
-
## Pasta `database/` (
|
|
133
|
+
## Pasta `database/` (migrations com Alembic)
|
|
134
134
|
|
|
135
|
-
Mesma estrutura em todo app, ao lado de `angular/`, `graphql/` e `server/`.
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
`
|
|
139
|
-
|
|
135
|
+
Mesma estrutura em todo app (Python ou Node: o argos também), ao lado de `angular/`, `graphql/` e `server/`. O
|
|
136
|
+
schema é versionado com **Alembic**, sem models: cada migration é SQL. O Alembic grava em cada banco (tabela
|
|
137
|
+
`alembic_version`) a última que rodou e aplica só as que faltam. `ambiente.py`, `bootstrap.py`, `seed.py`,
|
|
138
|
+
`migrations/env.py`, `migrations/util.py`, o template, `alembic.ini`, `pyproject.toml` e `tests/` são iguais entre os
|
|
139
|
+
apps, a menos do nome do app, das schemas e das tabelas de referência/fora do seed.
|
|
140
140
|
|
|
141
141
|
```
|
|
142
142
|
database/
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
tests/ pytest sem rede nem banco real; tests/pg = PGlite (Postgres em memória) para os testes de SQL
|
|
143
|
+
alembic.ini sem conexão (vem do ambiente); script_location = migrations, revision_environment = true
|
|
144
|
+
ambiente.py env/.env.<local|dev|homol|prod> (fora do git) ou variáveis do processo; DATABASE_URL vence
|
|
145
|
+
migrations/
|
|
146
|
+
env.py -x env=<ambiente> (padrão local); transação única + advisory lock; prod pede confirmação
|
|
147
|
+
(-x confirmar=sim no pipeline); numera as novas em sequência (0002, 0003...)
|
|
148
|
+
util.py executar_sql / executar_arquivo: SQL direto no driver (':' não vira parâmetro)
|
|
149
|
+
script.py.mako modelo de migration nova (upgrade com executar_sql; downgrade opcional)
|
|
150
|
+
versions/0001_linha_de_base.py + .sql schema inicial + dados de referência; 0002_..., 0003_...
|
|
151
|
+
bootstrap.sql + .py CREATE ROLE/DATABASE <app> + REVOKE CONNECT FROM PUBLIC; senha por :'role_password'
|
|
152
|
+
seed.py + seed/ cadastros de ambiente, NN-<schema>.<tabela>.sql (ver abaixo) -- não são migrations
|
|
153
|
+
env/.env.example POSTGRESQL_HOST/PORT/DATABASE/USER/PASSWORD (+ POSTGRESQL_SUPERUSER(_PASSWORD) do bootstrap)
|
|
154
|
+
pyproject.toml atalhos do poe
|
|
155
|
+
requirements*.txt alembic, python-dotenv, SQLAlchemy, psycopg2-binary (+ pytest, poethepoet)
|
|
156
|
+
tests/ migrations e seed de verdade num Postgres em memória (tests/pg: PGlite exposto por socket)
|
|
158
157
|
```
|
|
159
158
|
|
|
160
|
-
|
|
161
|
-
(pulam as checagens que dependem de tabela/migration) e passam a valer a partir da primeira.
|
|
162
|
-
|
|
163
|
-
Uso:
|
|
159
|
+
Uso (venv ativa):
|
|
164
160
|
|
|
165
161
|
```bash
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
162
|
+
poe migrate homol # alembic -x env=homol upgrade head
|
|
163
|
+
poe status prod # alembic -x env=prod current
|
|
164
|
+
poe historico # alembic history
|
|
165
|
+
poe nova "adiciona coluna x" # cria migrations/versions/<próximo número>_adiciona_coluna_x.py
|
|
166
|
+
poe bootstrap homol # role+database, uma vez por servidor Postgres (superuser do env)
|
|
167
|
+
poe seed homol # aplica seed/ num ambiente novo, depois do migrate
|
|
168
|
+
poe seed-regerar prod # regrava seed/ a partir do banco (sessão só de leitura)
|
|
169
|
+
poe test
|
|
170
170
|
```
|
|
171
171
|
|
|
172
172
|
Regras:
|
|
173
173
|
|
|
174
|
-
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
174
|
+
- **Mudança de schema = uma migration nova**, com o SQL que roda num banco que já tem dado (`ALTER TABLE ...`,
|
|
175
|
+
`CREATE INDEX ...`, `UPDATE` de dado de referência), dentro de `executar_sql`. Nunca edite migration que já rodou
|
|
176
|
+
em algum banco: corrija com outra. `downgrade` é opcional (deixe o `raise` se voltar não faz sentido).
|
|
177
|
+
- As migrations conectam como o **usuário do app** (o role do bootstrap): tabela nova já nasce dele.
|
|
178
|
+
- **Ordem do deploy**: `poe migrate <ambiente>` antes de subir a versão do serviço que usa a coluna nova. Migration
|
|
179
|
+
destrutiva (DROP) só depois que nenhuma versão no ar lê o que ela remove.
|
|
180
|
+
- **Dado de referência** (o que o código usa por id: status, tipos, etapas) vai por migration. **Cadastro de
|
|
181
|
+
ambiente** (clients, apps, origins...) vai no seed: `INSERT ... ON CONFLICT (pk) DO UPDATE`, gerado por
|
|
182
|
+
`poe seed-regerar` (nunca à mão), aplicado numa transação só. Histórico/log (builds, tentativas de login,
|
|
183
|
+
auditoria) não entra em nenhum dos dois.
|
|
184
|
+
- **Nunca dado real de pessoa no seed** (login, nome, e-mail, vínculo federado, MFA, membro de grupo), em nenhum app:
|
|
185
|
+
usuário de seed é fictício (`usuarioNN`, `usuarioNN@exemplo.com`) ou o dono do ambiente. O `seed-regerar` a partir de
|
|
186
|
+
produção traz pessoas reais de volta: reverta as tabelas de identidade e confira o diff antes de commitar. Dado
|
|
187
|
+
pessoal no histórico só sai reescrevendo o histórico.
|
|
188
|
+
- Segredo no seed só cifrado pelo serviço (ex.: `enc:v2:` do hefesto) ou em hash; um teste recusa o que estiver em
|
|
189
|
+
claro.
|
|
190
|
+
- Banco que já existia antes do Alembic: `alembic -x env=<ambiente> stamp 0001` uma vez (marca a linha de base sem
|
|
191
|
+
executar), depois `poe migrate` normalmente.
|
|
192
|
+
- App novo: `0001_linha_de_base` só com os `CREATE SCHEMA`; seed vazio.
|
|
189
193
|
|
|
190
194
|
Divergências observadas:
|
|
191
195
|
|
|
192
196
|
| Tema | Visto | Recomendado |
|
|
193
197
|
|---|---|---|
|
|
194
|
-
| Migrations | fora de `database
|
|
195
|
-
| `build.py` | versões com e sem `--seed`, relatório de erro e `newline=""` | a versão completa acima |
|
|
198
|
+
| Migrations | fora de `database/`, ou o serviço migrando na subida | Alembic em `database/migrations/versions/`, rodado por `poe migrate` antes do deploy |
|
|
196
199
|
| Seed | `DO NOTHING` por nome vs `DO UPDATE` por PK literal | regra da lista acima |
|
|
197
200
|
| Commit | no repository (todos) | `flush` no repository, `commit` no service quando a operação tem várias escritas |
|
|
@@ -267,7 +267,7 @@ Nomes de variáveis usados (sem valores):
|
|
|
267
267
|
| Ambiente | `APP_ENV`, `DEBUG`, `PORT`, `API_PREFIX`, `ALLOWED_HOSTS`, `API_DOCS` |
|
|
268
268
|
| Orfeu/Argos | `AUTHORIZER_URL`, `REALM_ID`, `APP_ID`, `APP_SECRET`, `AUTHORIZER_TLS_VERIFY`, `ARGOS_ADMIN_SERVER_URL` (se chamar o admin do Argos) |
|
|
269
269
|
| Postgres | `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `MIN_CONNECTION_COUNT`, `MAX_CONNECTION_COUNT` |
|
|
270
|
-
| Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
|
|
270
|
+
| Redis | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` (índice próprio do app — dois apps nunca no mesmo índice do mesmo Redis), `REDIS_CLIENT_NAME` (nome das conexões, padrão `<app>-server`; ver integracoes.md), + timeouts/prefixo `<app>:` de canal se usar pub/sub |
|
|
271
271
|
| Processo | `APP_ROLE` (`all`/`api`/`collector`) quando há collectors — ver integracoes.md |
|
|
272
272
|
|
|
273
273
|
Serviço com **vários bancos** usa o padrão de prefixo: `DB_ENTRIES=<nome1>,<nome2>` e, para cada nome,
|
|
@@ -285,7 +285,7 @@ atualizar: troque a versão, recrie o ambiente do zero e rode a suíte.
|
|
|
285
285
|
# Dependências DIRETAS (o que o código importa), com versão exata.
|
|
286
286
|
fastapi==0.142.2
|
|
287
287
|
uvicorn[standard]==0.54.0 # [standard]: uvloop + httptools (HTTP mais rápido no Linux)
|
|
288
|
-
orfeu[fastapi]==1.
|
|
288
|
+
orfeu[fastapi]==1.2.0
|
|
289
289
|
pydantic-settings==2.15.0
|
|
290
290
|
python-dotenv==1.2.4
|
|
291
291
|
loguru==0.7.3
|
|
@@ -91,10 +91,18 @@ pool = redis.ConnectionPool(
|
|
|
91
91
|
socket_connect_timeout=..., socket_timeout=...,
|
|
92
92
|
health_check_interval=30, # testa conexão ociosa antes de reusar
|
|
93
93
|
retry_on_timeout=True,
|
|
94
|
+
client_name=s.redis_client_name, # CLIENT SETNAME em toda conexão do pool (padrão "<app>-server")
|
|
94
95
|
)
|
|
95
96
|
app.state.redis = redis.Redis(connection_pool=pool)
|
|
96
97
|
```
|
|
97
98
|
|
|
99
|
+
- **Toda conexão nomeada (obrigatório, acropole `arquitetura.md` §3.1).** `redis_client_name: str =
|
|
100
|
+
"<app>-server"` nas settings (env `REDIS_CLIENT_NAME`, sem espaços — valide; vazio = padrão) e `client_name` no
|
|
101
|
+
`ConnectionPool`: vale para todas as conexões do pool, inclusive `pubsub()`. É o que aparece no campo `name=`
|
|
102
|
+
do `CLIENT LIST` e no redis_exporter para achar quem estoura o `maxclients`. Conexão fora do pool (`redis.Redis(
|
|
103
|
+
host=...)` solto, um worker) também leva `client_name`, com papel sufixado (`<app>-server-worker`). Teste:
|
|
104
|
+
`pool.connection_kwargs["client_name"]` com o padrão e com `REDIS_CLIENT_NAME` definido.
|
|
105
|
+
|
|
98
106
|
- Dependência `get_redis(request)` em `shared/dependencies.py` (um serviço usa `app.state.redis`, outro
|
|
99
107
|
`app.state.redis_client` — escolha `redis`).
|
|
100
108
|
- Instância compartilhada entre projetos → **prefixo de chave/canal** por projeto, configurável.
|
package/skills/hefesto/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
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,
|
|
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 — e o MCP de deploy (hefesto-mcp), com que um agente de IA consulta e faz deploy/redeploy das aplicações que a pessoa opera (x-app-token pessoal, escopos deploy.*). Use ao preparar um app para entrar no Hefesto, cadastrar ou revisar o deploy dele, investigar build/deploy/rota que falhou, configurar o .mcp.json de um agente para o Hefesto ou fazer deploy pelas tools do hefesto-mcp. 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
4
|
---
|
|
5
5
|
|
|
6
6
|
# hefesto
|
|
@@ -19,7 +19,7 @@ contrato entre os dois: o que não foi publicado lá não pode ser implantado.
|
|
|
19
19
|
|
|
20
20
|
Skills relacionadas: **docker** (como escrever o Dockerfile que o Hefesto builda), **fastapi**,
|
|
21
21
|
**express**, **apollo**, **angular** (o app em si), **orfeu** (identidade do app no Argos, auditoria
|
|
22
|
-
e o flush dela no SIGTERM).
|
|
22
|
+
e o flush dela no SIGTERM), **auto-servico** (o MCP equivalente do Argos).
|
|
23
23
|
|
|
24
24
|
## Regras essenciais
|
|
25
25
|
|
|
@@ -37,19 +37,24 @@ e o flush dela no SIGTERM).
|
|
|
37
37
|
service publicado em `/meu-app/api` precisa responder em `/meu-app/api/...` (prefixo configurável
|
|
38
38
|
no app: `API_PREFIX`, `root_path`, `CONTEXT_PATH`). Para **site** o prefixo é removido, mas o
|
|
39
39
|
`baseHref` do Angular tem que ser o próprio path, senão os assets saem da raiz e dão 404.
|
|
40
|
+
O path é sempre o **contexto do app** (`/<app>`, `/<app>/server`, `/<app>/mcp`): nunca publique nem
|
|
41
|
+
configure um serviço em `/api` genérico, nem troque o contexto para fazer uma URL funcionar.
|
|
40
42
|
5. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
|
|
41
43
|
`podman run` por um `--env-file` temporário (600, apagado logo depois; nunca `-e K=V` no argv) —
|
|
42
44
|
**só no próximo deploy/redeploy/rollback**. Arquivos `.env.*` não vão para a imagem
|
|
43
45
|
(`.dockerignore`). Segredo **sem valor padrão** no Dockerfile/código: faltou no cadastro, o app cai na
|
|
44
46
|
subida em vez de aceitar `changeme`.
|
|
45
|
-
6. **Processo principal recebe o SIGTERM.** Toda troca de versão
|
|
46
|
-
depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
|
|
47
|
+
6. **Processo principal recebe o SIGTERM.** Toda troca de versão para a versão antiga com SIGTERM (até
|
|
48
|
+
30 s, depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
|
|
47
49
|
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
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
50
|
+
7. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O deploy de
|
|
51
|
+
service é um rollout: a versão nova sobe ao lado da atual e só entra se o `health_path` responder
|
|
52
|
+
< 400 (sem ele, só a porta é conferida); não ficou saudável, é descartada e a atual continua no ar.
|
|
53
|
+
8. **Versão é do registry**: tag `[<instalação>.]<ambiente>-<major>.<minor>.<fix>.<test>` (ex.:
|
|
54
|
+
`hml1.homol-1.4.0.2`; o prefixo é o `HEFESTO_INSTANCE_ID`). O build escolhe qual parte incrementar e o
|
|
55
|
+
Deploy implanta exatamente a imagem que ele produziu; a retenção mantém só as últimas N por ambiente
|
|
56
|
+
desta instalação (padrão 5), menos as que algum worker está rodando. Rollback só para versão que ainda
|
|
57
|
+
existe no registry.
|
|
53
58
|
9. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
|
|
54
59
|
workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
|
|
55
60
|
distribuído. Ver `references/preparar-app.md`.
|
|
@@ -63,11 +68,12 @@ Solicitação "Redeploy de Serviços|Sites" Início → Deploy → Fim
|
|
|
63
68
|
Início valida app, agent, worker e se o repositório é do MESMO ambiente do origin do worker
|
|
64
69
|
Build Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
|
|
65
70
|
→ push <registry>/<app>:<ambiente>-<versão> → retenção das antigas
|
|
66
|
-
Deploy Hefesto → Talos do origin: pull da
|
|
67
|
-
service:
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
+
Deploy Hefesto → Talos do origin: pull da imagem que o Build gravou (Redeploy: a mais nova do ambiente)
|
|
72
|
+
service: rollout — sobe <nome>-next, espera o /health, troca e remove a antiga (sem downtime;
|
|
73
|
+
não ficou saudável = descarta a nova e a atual segue no ar)
|
|
74
|
+
site: create (sem rodar) → copia /dist para pasta nova → troca atômica do link
|
|
75
|
+
→ Hefesto regenera o Caddyfile do origin; o Talos valida e recarrega o Caddy
|
|
76
|
+
Rollback solicitação própria (Início → Deploy → Fim) com uma versão escolhida da lista do registry
|
|
71
77
|
```
|
|
72
78
|
|
|
73
79
|
Cada etapa grava o histórico (`current` → `processing` → `success`/`error`, com a mensagem) e
|
|
@@ -109,6 +115,32 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
|
|
|
109
115
|
- **Build passa local e falha no Ciclope**: depende de arquivo ignorado pelo git, de `.npmrc` local
|
|
110
116
|
ou de `node_modules` do contexto.
|
|
111
117
|
|
|
118
|
+
## Deploy por um agente de IA (MCP)
|
|
119
|
+
|
|
120
|
+
O **hefesto-mcp** (`POST <host>/hefesto/mcp`, Streamable HTTP) deixa um agente fazer, por tools, o que o Operador faz
|
|
121
|
+
na tela de Operação. Não tem regra própria: cada tool chama o hefesto-server **com o token da pessoa**, então ela só
|
|
122
|
+
vê e opera as aplicações dos grupos dela (Desenvolvedor/Administrador: todas). **Uma conexão por pessoa**, com o
|
|
123
|
+
token de aplicação pessoal (`x-app-token`, criado logado no Hefesto, em variável de ambiente, nunca no git):
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{ "mcpServers": { "hefesto": { "type": "http", "url": "https://<host>/hefesto/mcp",
|
|
127
|
+
"headers": { "x-app-token": "${HEFESTO_TOKEN}" } } } }
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`x-mcp-scopes: deploy.*.read` dá uma conexão só de consulta. O agente trabalha assim:
|
|
131
|
+
|
|
132
|
+
1. `getContext` → `listApps(search)` → `getApp(app_id)`: por ambiente, o repositório e os workers (servidor, status,
|
|
133
|
+
versão em execução). Todo id sai daí; nunca suposição.
|
|
134
|
+
2. Mostre o que muda (versão atual → nova, servidor/ambiente) e **confirme**, principalmente em produção.
|
|
135
|
+
3. `deployApp(app_id, worker_id, part)` (build + implantação) ou `redeployApp(app_id, worker_id)` (só reimplanta a
|
|
136
|
+
mais recente); `scheduled_for` agenda. A resposta volta na hora com o `requested_id`.
|
|
137
|
+
4. `getRequest` até `finished=true`; falhou → etapa com erro e `getBuildLog` (final do log).
|
|
138
|
+
|
|
139
|
+
Também estão no MCP: `cancelRequest`, `rollbackApp` (abre uma solicitação de Rollback; exige a permissão de
|
|
140
|
+
rollback no Argos), `getWorkerHistory` e `listEnvironmentVars`/`setEnvironmentVars` (segredos sem valor). Cadastros
|
|
141
|
+
(app, repositório, domínio, catálogos do motor) ficam na tela. Tools, roteiros e erros:
|
|
142
|
+
`references/mcp-tools.md`, `references/mcp-roteiros.md`, `references/mcp-diagnostico.md`.
|
|
143
|
+
|
|
112
144
|
## Índice de referências
|
|
113
145
|
|
|
114
146
|
| Arquivo | Conteúdo |
|
|
@@ -117,3 +149,6 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
|
|
|
117
149
|
| `references/fluxo.md` | Deploy ponta a ponta (Ciclope, registry, Talos, Caddy), versões e retenção, redeploy, rollback, solicitações e seus estados |
|
|
118
150
|
| `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
151
|
| `references/diagnostico.md` | Onde olhar (histórico, logs do container, Caddyfile), mensagens de erro do Hefesto e o que significam, erros comuns com causa |
|
|
152
|
+
| `references/mcp-tools.md` | hefesto-mcp: tools com argumentos, escopos, resources e prompts |
|
|
153
|
+
| `references/mcp-roteiros.md` | hefesto-mcp: deploy, redeploy, agendamento, vários workers, falha e revisão do que está rodando |
|
|
154
|
+
| `references/mcp-diagnostico.md` | hefesto-mcp: erros ao conectar e nas tools, e falhas por etapa da solicitação |
|
|
@@ -10,8 +10,11 @@
|
|
|
10
10
|
3. **Status/estatísticas do container**: reiniciando em loop = processo morrendo na subida (config,
|
|
11
11
|
porta, dependência).
|
|
12
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
|
-
|
|
13
|
+
(`<app>-<porta>:<porta do app>`) e domínio que o Hefesto gerou. Origin marcado **"Caddy desatualizado"**:
|
|
14
|
+
o último envio falhou (a aba Caddy mostra o erro e a próxima tentativa); use **Ressincronizar Caddy**.
|
|
15
|
+
5. **Status do worker e o motivo** (tela de Aplicações, embaixo do status; `status_message` no MCP): deploy
|
|
16
|
+
desfeito pelo health check, falha do Talos ou reconciliação depois de um restart.
|
|
17
|
+
6. **`/health` pelo domínio e pelo path**: separa "app quebrado" de "rota errada".
|
|
15
18
|
|
|
16
19
|
## Mensagens do Hefesto
|
|
17
20
|
|
|
@@ -28,6 +31,12 @@
|
|
|
28
31
|
| podman login failed | usuário/senha do registry | cadastro do registry |
|
|
29
32
|
| 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
33
|
| podman cp ... /dist ... no such file | site buildado sem `/dist` na raiz | estágio `site` precisa de `COPY --from=build .../browser /dist` |
|
|
34
|
+
| Deploy de `<versão>` desfeito automaticamente: A nova versão não ficou saudável (...) | a versão nova não respondeu < 400 no `health_path` (ou não abriu a porta) dentro do prazo; a anterior continua no ar | leia as últimas linhas da nova versão na mensagem; corrija a subida ou o `/health` |
|
|
35
|
+
| A imagem buildada por esta solicitação (...) não está mais no registry | a retenção apagou a imagem entre o Build e o Deploy | faça um novo Deploy |
|
|
36
|
+
| Interrompida: o server reiniciou durante a etapa X | o hefesto-server caiu no meio do Build/Deploy | confira o status do worker e use **Avançar** |
|
|
37
|
+
| A solicitação já está em execução (409) | outro avanço da mesma solicitação está rodando | espere terminar |
|
|
38
|
+
| O Talos recusou o Caddyfile (caddy validate) | configuração gerada inválida (domínio ou path estranho) | a mensagem traz a saída do validate; o Caddyfile anterior continua ativo |
|
|
39
|
+
| Rollback exige a permissão de rollback no Argos | usuário sem `apps:agents:workers:rollback` | peça a permissão ao administrador do Argos |
|
|
31
40
|
| nenhuma função registrada para este step | etapa adicionada ao fluxo sem implementação no servidor | remova a etapa do fluxo ou implemente |
|
|
32
41
|
| 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
42
|
|
|
@@ -45,9 +54,10 @@
|
|
|
45
54
|
| Site: build falha com "Configuration 'x' is not set" | nome do ambiente sem configuração no `angular.json` | `CONFIGURATION` = nome do ambiente, exato |
|
|
46
55
|
| Site antigo depois do deploy | cache do navegador no `index.html` | arquivos com hash podem ter cache longo; `index.html` não |
|
|
47
56
|
| 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
|
|
49
|
-
|
|
|
50
|
-
|
|
|
57
|
+
| Variável nova não aparece | variáveis só entram quando o container é criado | faça Redeploy |
|
|
58
|
+
| Worker preso em "deploying" | o server caiu no meio do rollout | a reconciliação resolve sozinha em até ~15 min (vira `running` ou `failed`, com o motivo) |
|
|
59
|
+
| Deploy "concluído" mas app fora | o `/health` responde < 400 antes de a app estar pronta (ou não há `health_path` e a porta abre cedo) | faça o `/health` conferir as dependências de verdade; sem ele, o Talos só confere a porta |
|
|
60
|
+
| Cada deploy demora 30 s a mais; auditoria perdida | SIGTERM não chega ao processo (o rollout espera até 30 s antes de matar) | CMD em forma exec, app trata SIGTERM (ver **docker**) |
|
|
51
61
|
| 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
62
|
| Build lento sempre do zero | `COPY . .` antes do install, ARG antes do install, contexto com `node_modules`/`.git` | ver **docker** |
|
|
53
63
|
| 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 |
|