@acropole/skills 1.6.0 → 1.7.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.
@@ -37,9 +37,11 @@ motivo em `references/porques.md`; modelos completos e comentados em `references
37
37
  busybox no Alpine, `python -c` no slim). Com Podman/Buildah só é gravado em imagem formato
38
38
  `docker`; no deploy, o `/health` é verificado de fora de qualquer jeito.
39
39
  9. **`ENV PORT` + `EXPOSE`** com a porta cadastrada no Hefesto; o processo escuta em `0.0.0.0`.
40
- 10. **ARG é build, ENV é runtime.** Build arg só para o que muda o artefato (ex.:
41
- `CONFIGURATION` do Angular), declarado **depois** do install. Configuração por ambiente (URLs,
42
- banco, identidade) vem do ambiente em runtime, nunca de `ENV` fixo no Dockerfile.
40
+ 10. **ARG é build, ENV é runtime; uma imagem por versão.** A mesma imagem roda em homol e prod:
41
+ nada de ambiente no build (o Angular sai **sempre** de `ng build --configuration production`, sem
42
+ `ARG CONFIGURATION`). Build arg só para o que muda o artefato e não é ambiente, declarado **depois**
43
+ do install. Configuração por ambiente (URLs, banco, identidade) vem em runtime: variáveis do deploy
44
+ no backend, `config.json` no front (ver regra 16), nunca `ENV` fixo no Dockerfile.
43
45
  11. **`.dockerignore` na raiz do contexto** com `.git`, dependências locais, `dist`, caches e
44
46
  `.env`/`.env.*` (menos `.env.example`). Consequência intencional: o app no container lê config
45
47
  só do ambiente.
@@ -51,13 +53,19 @@ motivo em `references/porques.md`; modelos completos e comentados em `references
51
53
  apagado no `finally`), nunca `-e K=V` no argv (aparece em `ps` e em log). Nome que vira caminho é
52
54
  validado e contido na raiz (`Path.resolve()`) antes de `rmtree`/escrita.
53
55
  15. **`.gitattributes` com `*.sh text eol=lf`**: script com CRLF quebra no container.
56
+ 16. **Front Angular escolhe o ambiente em runtime.** O `dist` leva `brand/config/<amb>.json` de todos os
57
+ ambientes e **nenhum** `config.json`; quem gera o `config.json` é o deploy (site: o Talos copia
58
+ `brand/config/<amb>.json`; SPA servida por um servidor do app: o servidor serve o arquivo de
59
+ `APP_ENV`). `src/config.json` (o do `ng serve`) vai no `.dockerignore`. Estágio `dev`: `ENV APP_ENV=dev`
60
+ + `scripts/use-config.mjs "$APP_ENV"` antes do `ng serve`.
54
61
 
55
62
  ## Por stack (resumo — modelos em `references/modelos.md`)
56
63
 
57
- **Angular (site)** — estágios `dev` (`ng serve`, para compose local), `build`
58
- (`ng build --configuration $CONFIGURATION`, com `ARG CONFIGURATION=prod` depois do `npm ci` e cache
59
- do `.angular/cache`) e **`site`**: `FROM scratch`, `COPY --from=build /app/dist/<projeto>/browser
60
- /dist`, `CMD ["unused"]`. A imagem nunca roda: o Talos a cria, copia o `/dist` e o Caddy do servidor
64
+ **Angular (site)** — estágios `dev` (`use-config` + `ng serve`, para compose local; `APP_ENV`
65
+ escolhe o ambiente), `build` (sempre `ng build --configuration production`, sem `ARG CONFIGURATION`,
66
+ com cache do `.angular/cache`) e **`site`**: `FROM scratch`, `COPY --from=build
67
+ /app/dist/<projeto>/browser /dist`, `CMD ["unused"]`. Uma imagem para todos os ambientes; o
68
+ `config.json` do ambiente é gerado no deploy. A imagem nunca roda: o Talos a cria, copia o `/dist` e o Caddy do servidor
61
69
  serve os arquivos. É o **último** estágio, então compose local precisa de `target: dev`. Budget
62
70
  estourado (`maximumError`) quebra o build — conserte o bundle (ver **angular**).
63
71
 
@@ -86,6 +94,8 @@ background no lifespan: cada worker do uvicorn roda o lifespan inteiro e a taref
86
94
  | `docker create` falha: "no command specified" | estágio `scratch` sem `CMD` |
87
95
  | Site extraído sem arquivos | build não copiou para `/dist` (ou copiou `dist/<proj>` em vez de `.../browser`) |
88
96
  | Compose local sobe um container que sai na hora | estágio final é o `site`; faltou `target: dev` |
97
+ | Front sobe em branco com erro do `loadRuntimeConfig` no console | sem `config.json` ao lado do `index.html`: deploy sem o ambiente (Talos antigo, `APP_ENV` faltando) ou `brand/config/<amb>.json` ausente no build |
98
+ | Front em prod falando com os endereços de homol | `src/config.json` local entrou na imagem (faltou no `.dockerignore`) ou imagem antiga buildada por ambiente |
89
99
  | `EACCES` ao escrever arquivo | `USER` não-root e pasta sem `--chown` |
90
100
  | Tarefas agendadas executando em dobro | `uvicorn --workers N` (ou várias réplicas) com scheduler no lifespan |
91
101
  | Credencial aparece em `docker history`/`inspect` | `ARG`/`ENV` de token, ou `.npmrc` copiado |
@@ -15,24 +15,27 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
15
15
  timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
16
16
  COPY . .
17
17
  EXPOSE 4200
18
- CMD ["./node_modules/.bin/ng", "serve", "--configuration", "dev", "--host", "0.0.0.0", "--no-hmr", "--port", "4200"]
18
+ # Ambiente em runtime: APP_ENV (padrão dev) escolhe src/brand/config/<APP_ENV>.json, copiado para
19
+ # src/config.json antes do ng serve; ambiente sem arquivo derruba o container com a lista dos que existem.
20
+ ENV APP_ENV=dev
21
+ CMD ["sh", "-c", "node scripts/use-config.mjs \"$APP_ENV\" && exec ./node_modules/.bin/ng serve --host 0.0.0.0 --no-hmr --port 4200"]
19
22
 
20
- # ── build: o build de verdade, por ambiente ─────────────────────────────────────────────────
23
+ # ── build: o build de verdade, UM para todos os ambientes ───────────────────────────────────
21
24
  FROM node:22-slim AS build
22
25
  WORKDIR /app
23
26
  COPY package.json package-lock.json ./
24
27
  RUN --mount=type=cache,target=/root/.npm,sharing=locked \
25
28
  timeout -k 10 600 npm ci --prefer-offline --no-audit --no-fund
26
29
  COPY . .
27
- # Depois do install: um ARG entra no ambiente dos RUN seguintes; declarado antes, cada
28
- # ambiente invalidaria o cache do npm ci. O Hefesto passa o nome do ambiente.
29
- ARG CONFIGURATION=prod
30
+ # Imagem única: sempre "production", sem ARG CONFIGURATION e sem endereço embutido. O ambiente vem em
31
+ # runtime do config.json que o deploy gera. Um --build-arg CONFIGURATION antigo só gera aviso.
30
32
  # Cache do Angular CLI fora da imagem (com cli.cache.environment = "all" no angular.json).
31
33
  RUN --mount=type=cache,target=/app/.angular/cache,sharing=locked \
32
- timeout -k 10 300 ./node_modules/.bin/ng build --configuration $CONFIGURATION
34
+ timeout -k 10 300 ./node_modules/.bin/ng build --configuration production
33
35
 
34
36
  # ── site: só transporta o /dist. Nunca roda; é o ÚLTIMO estágio (o --target do Hefesto) ──────
35
37
  FROM scratch AS site
38
+ # /dist leva brand/config/<amb>.json de todos os ambientes e NENHUM config.json (o Talos gera no deploy).
36
39
  COPY --from=build /app/dist/meu-app/browser /dist
37
40
  # `create` exige um comando no manifesto, mesmo que o container nunca rode (scratch não tem shell).
38
41
  CMD ["unused"]
@@ -103,8 +106,9 @@ COPY ui/package.json ui/package-lock.json ./
103
106
  RUN --mount=type=cache,target=/root/.npm,sharing=locked \
104
107
  timeout -k 10 600 npm ci --no-audit --no-fund
105
108
  COPY ui/. .
106
- ARG CONFIGURATION=prod
107
- RUN timeout -k 10 300 npm run build -- --configuration=$CONFIGURATION
109
+ # Imagem única: sempre production. `rm -f src/config.json`: o do ng serve nunca entra na imagem.
110
+ RUN rm -f src/config.json \
111
+ && timeout -k 10 300 ./node_modules/.bin/ng build --configuration production
108
112
 
109
113
  FROM node:22-alpine AS server-build
110
114
  WORKDIR /app
@@ -126,11 +130,19 @@ COPY --from=ui-build /ui/dist /ui/dist
126
130
  ENV NODE_ENV=production PORT=3000 \
127
131
  UI_STATIC_PATH=/ui/dist/meu-app/browser \
128
132
  UI_BASE_PATH=/meu-app
133
+ # APP_ENV (homol, prod...) NÃO vem da imagem: o deploy injeta. O servidor serve
134
+ # {UI_BASE_PATH}/config.json a partir de {UI_STATIC_PATH}/brand/config/${APP_ENV}.json.
129
135
  EXPOSE 3000
130
136
  USER node
131
137
  CMD ["node", "dist/index.js"]
132
138
  ```
133
139
 
140
+ O servidor lê e valida `brand/config/${APP_ENV}.json` **na subida** e registra a rota
141
+ `{UI_BASE_PATH}/config.json` **antes** do `express.static` (um `config.json` solto no build nunca vale no lugar
142
+ do ambiente do deploy), com `Cache-Control: no-store`. Em produção, `APP_ENV` ausente/inválido (`^[a-z0-9-]+$`) ou
143
+ arquivo inexistente/quebrado **derruba a subida** com a lista dos ambientes do build; fora dela só avisa e a rota
144
+ responde 404.
145
+
134
146
  O `.dockerignore` fica na raiz do contexto (a pasta que contém `ui/` e `server/`); os de subpastas
135
147
  não têm efeito.
136
148
 
@@ -202,10 +214,12 @@ coverage
202
214
  !.env.example
203
215
  Dockerfile
204
216
  .dockerignore
217
+ # Angular: o config.json do ng serve (use-config); o deploy é quem escolhe o ambiente
218
+ src/config.json
205
219
  ```
206
220
 
207
221
  Contexto com subpastas (`ui/` + `server/`): use `**/node_modules`, `**/dist`, `**/.env`,
208
- `**/.env.*`, `!**/.env.example`.
222
+ `**/.env.*`, `!**/.env.example`, `**/src/config.json`.
209
223
 
210
224
  Python:
211
225
 
@@ -56,7 +56,7 @@ Com `COPY . .` antes do `npm ci`, qualquer commit reinstala tudo.
56
56
  - **Cache do Angular** (`.angular/cache` montado + `cli.cache.environment: "all"`): partes que não
57
57
  mudaram não são recompiladas.
58
58
  - **ARG depois do install**: um `ARG` vira variável de ambiente de todos os `RUN` seguintes e entra na
59
- chave de cache deles. `ARG CONFIGURATION` antes do `npm ci` faz cada ambiente reinstalar tudo.
59
+ chave de cache deles. Um `ARG` antes do `npm ci` faz cada valor diferente reinstalar tudo.
60
60
  - **Contexto pequeno** (`.dockerignore`): `.git` e `node_modules` locais mudam sempre e invalidam o
61
61
  `COPY . .`, além de inflar o envio do contexto.
62
62
 
@@ -217,13 +217,21 @@ deploy. A porta do `ENV PORT` precisa bater com a cadastrada na plataforma.
217
217
 
218
218
  | | Quando é lido | Fica na imagem | Use para |
219
219
  | --- | --- | --- | --- |
220
- | `ARG` | só durante o build | no histórico | o que muda o artefato: `CONFIGURATION` do Angular |
220
+ | `ARG` | só durante o build | no histórico | o que muda o artefato e **não** é ambiente (raro; o Angular não usa nenhum) |
221
221
  | `ENV` no Dockerfile | build e runtime | sim | padrões não sensíveis: `PORT`, `NODE_ENV`, `PYTHONUNBUFFERED`, caminhos internos |
222
222
  | variável no deploy (`--env-file`/`-e`) | runtime | não | tudo que muda por ambiente ou é segredo: banco, URLs, identidade no Argos — segredo **sem** valor padrão no Dockerfile |
223
223
 
224
- A mesma imagem deve poder rodar em qualquer ambiente trocando só as variáveis de runtime. A exceção
225
- é o site Angular: o navegador não lê variável de ambiente do servidor, então endpoints e `baseHref`
226
- entram no build (`CONFIGURATION`), e por isso há uma imagem por ambiente.
224
+ A mesma imagem roda em qualquer ambiente trocando só o que é de runtime — **inclusive o front
225
+ Angular**. O navegador não lê variável de ambiente do servidor, então o front lê um arquivo: o `dist`
226
+ leva `brand/config/<amb>.json` de todos os ambientes, e o deploy põe o do ambiente como `config.json` ao
227
+ lado do `index.html` (site: o Talos copia; SPA servida pelo servidor do app: ele serve o arquivo de
228
+ `APP_ENV`). No bootstrap, `loadRuntimeConfig` mescla esse arquivo no `environment`. Só o `baseHref`
229
+ continua no build (é igual em todos os ambientes).
230
+
231
+ Por que uma imagem só: o que foi testado em homologação é **exatamente** o que vai para produção
232
+ (mesmo digest), o deploy de prod não builda de novo (promove a imagem do mesmo commit) e a tag é só a
233
+ versão. A configuração antiga por ambiente (`ARG CONFIGURATION=<amb>` + `fileReplacements`) gerava um
234
+ artefato diferente por ambiente: o que ia para prod nunca tinha rodado em lugar nenhum.
227
235
 
228
236
  ## `.dockerignore`
229
237
 
@@ -232,6 +240,8 @@ entram no build (`CONFIGURATION`), e por isso há uma imagem por ambiente.
232
240
  - **`node_modules`, `.venv`**: as do host são de outro sistema operacional (binários nativos de
233
241
  Windows/macOS) e sobrescreveriam as instaladas no build pelo `COPY . .`.
234
242
  - **`dist`, `.angular`, `coverage`, caches**: artefatos locais que só invalidam cache.
243
+ - **`src/config.json`** (Angular): a cópia do ambiente que o `ng serve` usa. Dentro da imagem, um site
244
+ publicado sem `config_env` (Talos antigo) subiria com o ambiente de quem buildou.
235
245
  - **`.env`, `.env.*` (menos `.env.example`)**: segredo local fora da imagem. Efeito colateral
236
246
  desejado: no container o app **só** lê configuração do ambiente; se ele carrega
237
247
  `.env.<APP_ENV>`, o arquivo não existe e cada valor precisa ser cadastrado como variável. Um app
@@ -255,7 +265,10 @@ vai para o registry com tag e versão como qualquer outra, permite rollback e au
255
265
  publicado, e o Talos extrai `/dist` sem nunca executá-la. Daí as convenções:
256
266
  - estágio chamado `site` (é o `--target`);
257
267
  - conteúdo em `/dist` na raiz;
258
- - `CMD ["unused"]` porque criar um container exige comando no manifesto, e `scratch` não tem shell.
268
+ - `CMD ["unused"]` porque criar um container exige comando no manifesto, e `scratch` não tem shell;
269
+ - `/dist` com `brand/config/<amb>.json` de todos os ambientes e sem `config.json`: o Talos copia o do
270
+ ambiente para `config.json` antes de pôr a versão no ar (arquivo ausente ou JSON inválido = `422` e a
271
+ versão anterior continua).
259
272
 
260
273
  Ser o último estágio faz um `build` sem `--target` produzir a imagem `site`; para rodar o
261
274
  dev-server localmente, `target: dev`. Budgets do `angular.json` com `maximumError` estourado fazem o
@@ -27,37 +27,48 @@ e o flush dela no SIGTERM), **auto-servico** (o MCP equivalente do Argos).
27
27
  configurado (`--depth 1`) e builda na raiz do repo ou no `build_path` (subpasta, para monorepo).
28
28
  Nada de arquivo gerado localmente, `.env` ou `.npmrc` com credencial. Ver **docker**.
29
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
30
+ `site`: o Ciclope builda `--target site`; o estágio `site` tem o build estático em **`/dist` na raiz
31
+ da imagem** e nunca roda. Em qualquer tipo o build recebe `--build-arg CONFIGURATION=production`
32
+ (sempre o mesmo; o Dockerfile pode nem declarar o `ARG`).
33
+ 3. **Uma imagem por versão, a mesma em todos os ambientes.** O ambiente não entra no build; o front
34
+ escolhe o ambiente em runtime pelo `config.json`. Na implantação o Hefesto diz qual é: **site** →
35
+ `config_env=<ambiente>` para o Talos, que copia `brand/config/<ambiente>.json` para `config.json`
36
+ (Talos ≥ 1.1.13); **service** → o container recebe `APP_ENV=<ambiente>` (se a app cadastrou `APP_ENV`
37
+ nas variáveis dela, a dela vence) e o servidor do app serve o `config.json` da UI. `<ambiente>` = nome
38
+ cadastrado, em minúsculas. O app precisa ter `brand/config/<ambiente>.json` de cada ambiente no build
39
+ (ver **angular**).
40
+ 4. **A porta cadastrada no app é a porta em que o processo escuta dentro do container**, em
33
41
  `0.0.0.0`. O Caddy encaminha para `<nome-do-container>:<porta do app>` pela rede interna; a porta
34
42
  do worker é só o mapeamento no host. O Hefesto **não injeta `PORT`**: deixe o `ENV PORT` do
35
43
  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
44
+ 5. **O path do agent chega inteiro no service** (o Caddy usa `handle`, sem tirar o prefixo). Um
37
45
  service publicado em `/meu-app/api` precisa responder em `/meu-app/api/...` (prefixo configurável
38
46
  no app: `API_PREFIX`, `root_path`, `CONTEXT_PATH`). Para **site** o prefixo é removido, mas o
39
47
  `baseHref` do Angular tem que ser o próprio path, senão os assets saem da raiz e dão 404.
40
48
  O path é sempre o **contexto do app** (`/<app>`, `/<app>/server`, `/<app>/mcp`): nunca publique nem
41
49
  configure um serviço em `/api` genérico, nem troque o contexto para fazer uma URL funcionar.
42
- 5. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
50
+ 6. **Configuração vem do ambiente.** Variáveis são cadastradas por (app, ambiente) e entram no
43
51
  `podman run` por um `--env-file` temporário (600, apagado logo depois; nunca `-e K=V` no argv) —
44
52
  **só no próximo deploy/redeploy/rollback**. Arquivos `.env.*` não vão para a imagem
45
53
  (`.dockerignore`). Segredo **sem valor padrão** no Dockerfile/código: faltou no cadastro, o app cai na
46
54
  subida em vez de aceitar `changeme`.
47
- 6. **Processo principal recebe o SIGTERM.** Toda troca de versão para a versão antiga com SIGTERM (até
55
+ 7. **Processo principal recebe o SIGTERM.** Toda troca de versão para a versão antiga com SIGTERM (até
48
56
  30 s, depois SIGKILL). App que não trata SIGTERM, ou que roda atrás de `npm start`/`sh` sem `exec`,
49
57
  perde a fila de auditoria do Orfeu e atrasa todo deploy. Ver **docker**.
50
- 7. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O deploy de
58
+ 8. **`GET <prefixo>/health`** respondendo `200` só quando as dependências reais respondem. O deploy de
51
59
  service é um rollout: a versão nova sobe ao lado da atual e só entra se o `health_path` responder
52
60
  < 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.
58
- 9. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
59
- workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
60
- distribuído. Ver `references/preparar-app.md`.
61
+ 9. **Versão é do registry e da app**: tag `<registry>/<app>:<major>.<minor>.<fix>.<test>` (ex.:
62
+ `app-exemplo:1.4.0.2`), **sem ambiente nem prefixo de instalação**. O build escolhe qual parte
63
+ incrementar e o Deploy implanta exatamente a imagem que ele produziu. **Promoção**: o Build de um
64
+ ambiente reaproveita a imagem já publicada por outro quando repositório git, branch, `build_path`,
65
+ registry e commit batem — por isso o repositório de **homol aponta para `master`**, como o de prod;
66
+ deploy em homol e depois em prod do mesmo commit = um build só. Tags antigas
67
+ (`[<instalação>.]<ambiente>-x.y.z.w`, buildadas por ambiente) continuam listadas e implantáveis só no
68
+ próprio ambiente. Rollback só para versão que ainda existe no registry.
69
+ 10. **Background job em mais de uma réplica duplica.** Cada worker é um container completo; com dois
70
+ workers, um agendador no lifespan roda duas vezes. Separe o papel (API x coletor) ou use lock
71
+ distribuído. Ver `references/preparar-app.md`.
61
72
 
62
73
  ## Fluxo em uma tela
63
74
 
@@ -66,12 +77,14 @@ Solicitação "Deploy de Serviços|Sites" Início → Build → Deploy → Fim
66
77
  Solicitação "Redeploy de Serviços|Sites" Início → Deploy → Fim (sem build: última versão)
67
78
 
68
79
  Início valida app, agent, worker e se o repositório é do MESMO ambiente do origin do worker
69
- Build Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
70
- → push <registry>/<app>:<ambiente>-<versão> → retenção das antigas
80
+ Build mesmo commit de um build já publicado (deste ou de outro ambiente, mesma fonte)? reaproveita
81
+ senão Hefesto → Ciclope: clone (branch do repositório do ambiente) → podman build [--target site]
82
+ CONFIGURATION=production → push <registry>/<app>:<versão> → retenção das antigas
71
83
  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
84
+ service: rollout com APP_ENV=<ambiente> — sobe <nome>-next, espera o /health, troca e remove a
85
+ antiga (sem downtime; não ficou saudável = descarta a nova e a atual segue no ar)
86
+ site: create (sem rodar) → copia /dist para pasta nova → config_env: brand/config/<amb>.json
87
+ vira config.json → troca atômica do link
75
88
  → Hefesto regenera o Caddyfile do origin; o Talos valida e recarrega o Caddy
76
89
  Rollback solicitação própria (Início → Deploy → Fim) com uma versão escolhida da lista do registry
77
90
  ```
@@ -83,8 +96,12 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
83
96
 
84
97
  - [ ] Dockerfile na raiz do repo (ou do `build_path`), `.dockerignore` com `.git`, dependências
85
98
  locais, `dist` e `.env*`. Para site: estágio chamado `site` com `/dist`.
86
- - [ ] Site: uma configuração do Angular **com o nome exato de cada ambiente** do Hefesto
87
- (`dev`, `homol`, `prod`...), com `baseHref` igual ao path do agent.
99
+ - [ ] Front (site ou service com UI): `src/brand/config/<ambiente>.json` **com o nome exato de cada
100
+ ambiente** do Hefesto em minúsculas (`homol`, `prod`...), `loadRuntimeConfig` no `main.ts` e
101
+ `baseHref` igual ao path do agent. Service com UI: o servidor serve o `config.json` de `APP_ENV`.
102
+ - [ ] Repositório de homol no branch `master` (mesma URL, `build_path` e registry do de prod) para a
103
+ imagem de homol ser promovida a prod sem novo build.
104
+ - [ ] Site: Talos do origin ≥ 1.1.13 (o anterior ignora `config_env` e o site sobe sem `config.json`).
88
105
  - [ ] Service: escuta em `0.0.0.0:<porta cadastrada>`, responde sob o path do agent, tem
89
106
  `/health`, trata SIGTERM, CMD em forma exec.
90
107
  - [ ] Nenhum segredo com valor padrão (`ENV X=changeme`, `getenv("X", "...")`); `.gitattributes` com
@@ -102,8 +119,13 @@ publica em tempo real para a UI. Detalhes em `references/fluxo.md`.
102
119
 
103
120
  ## Armadilhas mais comuns (lista completa em `references/diagnostico.md`)
104
121
 
105
- - **"Configuration 'x' is not set in the workspace"** no build de site: o ambiente do Hefesto tem
106
- um nome que não existe no `angular.json`. O `CONFIGURATION` é o nome do ambiente, sem tradução.
122
+ - **Front sobe em branco, console com erro do `config.json`**: falta o ambiente em runtime — site com
123
+ Talos antigo (sem `config_env`), `brand/config/<ambiente>.json` ausente no build (o Talos responde
124
+ `422` e a versão anterior continua), ou service sem `APP_ENV`/servidor sem a rota do `config.json`.
125
+ - **Deploy de prod buildou de novo em vez de promover**: repositórios de homol e prod com branch, URL,
126
+ `build_path` ou registry diferentes, ou commit novo no master depois do deploy de homol.
127
+ - **"Configuration 'production' is not set"**: o `angular.json` não tem a configuração `production`
128
+ (resto do modelo antigo `prod`/`homol`).
107
129
  - **502 só na rota do app**: worker cadastrado mas container parado/caindo, ou o processo escuta em
108
130
  outra porta / em `127.0.0.1`.
109
131
  - **404 em tudo do service, mas `/health` direto no container funciona**: o app responde na raiz e
@@ -43,17 +43,21 @@ header HTTP, fora da linha de comando e dos logs. Use um token **só de leitura*
43
43
  Onde as imagens são publicadas e de onde os origins puxam. Tem URL, usuário/senha, `verify_ssl`
44
44
  (desligar só para registry com certificado de CA interna que os hosts não conhecem) e, opcionalmente,
45
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.
46
+ ambientes (e até várias instalações do Hefesto): a tag é só a versão da app (`<app>:x.y.z.w`), a mesma
47
+ imagem para todos os ambientes; as tags antigas (`[<instalação>.]<ambiente>-x.y.z.w`) levavam o ambiente.
47
48
 
48
49
  ### Repositório (`repository`) — um por (aplicação, ambiente)
49
50
  | Campo | Significado |
50
51
  | --- | --- |
51
52
  | URL | repositório git (HTTPS) |
52
- | branch | branch clonado para esse ambiente (ex.: `develop` em homol, `main` em prod) |
53
+ | branch | branch clonado para esse ambiente. Para promover a mesma imagem de homol para prod, os dois apontam para `master` |
53
54
  | `build_path` | subpasta usada como contexto do build (monorepo). Vazio = raiz. Não pode sair do repo. |
54
55
  | conector | credencial do clone |
55
56
  | registry | destino da imagem; sem ele não há build |
56
57
 
58
+ Repositórios de ambientes diferentes com a mesma URL, branch, `build_path` e registry formam uma **mesma
59
+ fonte**: o Build de um reaproveita (promove) a imagem que o outro já publicou para o mesmo commit.
60
+
57
61
  ### Build (`build`)
58
62
  Log das tentativas de build (status `building`/`built`/`failed`, quando). **A fonte da verdade do
59
63
  que existe é o registry**: a lista de versões mostrada é reconciliada com as tags publicadas (uma
@@ -63,10 +67,12 @@ removida).
63
67
  ## Infraestrutura
64
68
 
65
69
  ### 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
+ `dev`, `homol`, `prod`... O **nome**, em minúsculas, é o ambiente em runtime do front:
71
+ - site: `config_env=<ambiente>` no deploy; o Talos copia `brand/config/<ambiente>.json` para `config.json`;
72
+ - service: o container recebe `APP_ENV=<ambiente>` (a variável `APP_ENV` da app, se cadastrada, vence).
73
+
74
+ Precisa existir `src/brand/config/<ambiente>.json` com esse nome exato no front. O ambiente **não** entra mais
75
+ no build (sempre `CONFIGURATION=production`) nem na tag da imagem.
70
76
 
71
77
  ### Origin (`origin`)
72
78
  Um servidor com o **Talos** rodando (há também o tipo `kubernetes` no cadastro). Pertence a **um**
@@ -101,7 +107,8 @@ origin só serve os próprios agents. Agent **sem domínio vinculado** cai no bl
101
107
  Chave/valor por (aplicação, ambiente), iguais em todos os origins daquele ambiente. Aplicadas como
102
108
  um `--env-file` temporário (600, apagado logo depois) no `podman run` do próximo deploy, redeploy ou
103
109
  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).
110
+ há processo; a configuração do site é o `brand/config/<ambiente>.json` do build, escolhido no deploy). O service
111
+ recebe também `APP_ENV=<ambiente>`, a menos que a app tenha a sua.
105
112
 
106
113
  ## Operação
107
114
 
@@ -125,7 +132,8 @@ ou `error`, com a mensagem (no erro de build, o fim da saída do `podman build`)
125
132
  para diagnosticar. Mudanças são publicadas em tempo real para a UI.
126
133
 
127
134
  ### Deploy, Redeploy e Rollback
128
- - **Deploy**: builda uma versão nova e implanta.
135
+ - **Deploy**: builda uma versão nova e implanta — ou, se outro ambiente já publicou o mesmo commit da mesma
136
+ fonte, reaproveita aquela imagem (promoção) e implanta.
129
137
  - **Redeploy**: implanta a versão mais recente já publicada, sem build (útil depois de mudar
130
138
  variáveis ou para recriar um container).
131
139
  - **Rollback**: implanta uma versão anterior escolhida na lista do registry daquele ambiente.
@@ -51,7 +51,13 @@
51
51
  | 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 |
52
52
  | 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 |
53
53
  | Site: F5 numa rota dá 404 | `site_mode = static` | use `spa` para fallback no `index.html` |
54
- | Site: build falha com "Configuration 'x' is not set" | nome do ambiente sem configuração no `angular.json` | `CONFIGURATION` = nome do ambiente, exato |
54
+ | Build falha com "Configuration 'production' is not set" | `angular.json` ainda no modelo antigo (`prod`/`homol`...) | o build é sempre `production`; ver **angular** |
55
+ | Front: tela branca, console com erro ao carregar `config.json` | sem o ambiente em runtime: Talos < 1.1.13 (ignora `config_env`), service sem `APP_ENV` ou servidor sem a rota `<prefixo>/config.json` | atualize o Talos; confira o `APP_ENV` (ou a variável da app, que vence) e a rota no servidor |
56
+ | Site: deploy falha com `422` "a imagem não tem brand/config/<amb>.json" | o build não traz o arquivo do ambiente (nome diferente do cadastrado, ou fora do `assets` do `angular.json`) | `src/brand/config/<ambiente>.json` com o nome do ambiente em minúsculas; a versão anterior continua no ar |
57
+ | Service com UI cai na subida: "APP_ENV não definido" / "brand/config/x.json não existe" | `APP_ENV` sobrescrito errado nas variáveis da app, ou ambiente sem arquivo no build | remova o `APP_ENV` da app (o Hefesto injeta o nome do ambiente) ou crie o arquivo |
58
+ | Front em prod com endereços de homol | `src/config.json` local entrou na imagem e o deploy não gerou outro (Talos antigo), ou `homol.json`/`prod.json` trocados | `src/config.json` no `.dockerignore`; confira os arquivos de `src/brand/config/` |
59
+ | Deploy em prod buildou de novo em vez de reaproveitar a imagem de homol | repositórios dos ambientes com URL, branch, `build_path` ou registry diferentes; ou commit novo no branch desde o deploy de homol | repositório de homol em `master`, igual ao de prod |
60
+ | Redeploy em prod não pega a versão nova de homol | Redeploy só implanta o que foi buildado ou promovido **para o ambiente** | faça um Deploy em prod (promove) ou Rollback para a versão |
55
61
  | Site antigo depois do deploy | cache do navegador no `index.html` | arquivos com hash podem ter cache longo; `index.html` não |
56
62
  | 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 |
57
63
  | Variável nova não aparece | variáveis só entram quando o container é criado | faça Redeploy |
@@ -71,10 +77,13 @@
71
77
  ```bash
72
78
  git clone --depth 1 --single-branch --branch <branch> <url> /tmp/x && cd /tmp/x/<build_path>
73
79
  podman build -t teste . # service
74
- podman build --target site --build-arg CONFIGURATION=homol -t teste . # site
80
+ podman build --target site -t teste . # site (sempre production)
75
81
  podman run --rm --env-file .env.teste -p 8080:<porta do app> teste # service: confira /health
76
82
  ```
77
83
 
84
+ Site: para conferir o `/dist` como o Talos publica, extraia (`podman create` + `podman cp <id>:/dist ./site`),
85
+ copie `site/brand/config/homol.json` para `site/config.json` e sirva a pasta sob o `baseHref`.
86
+
78
87
  O `.env.teste` é local (fora do repo e com permissão restrita); segredo em `-e` fica no histórico do
79
88
  shell. Com Docker local funciona igual para a maioria dos casos; diferenças do Podman/Buildah estão na
80
89
  skill **docker**.
@@ -4,7 +4,7 @@
4
4
 
5
5
  ```
6
6
  solicitação (UI) registry
7
- usuário ───────────────▶ Hefesto ──build──▶ Ciclope ──push──▶ <app>:<amb>-x.y.z.w
7
+ usuário ───────────────▶ Hefesto ──build──▶ Ciclope ──push──▶ <app>:x.y.z.w
8
8
  │ │
9
9
  └──deploy──▶ Talos (origin do ambiente) ◀─┘ pull
10
10
  │
@@ -16,30 +16,40 @@
16
16
  ## 1. Início (validação)
17
17
 
18
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`;
19
+ - no Deploy: o repositório escolhido é o **do ambiente do origin** do worker (é ele que diz o branch e
20
+ em que histórico de builds a versão entra);
21
21
  - sanidade (só aviso em log): tipo da solicitação (Sites/Serviços) bate com o tipo do app. Quem decide
22
22
  o comportamento é sempre o tipo do app.
23
23
 
24
24
  ## 2. Build (Ciclope)
25
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
26
+ 1. **Mesmo commit = reaproveita (promoção).** Antes de buildar, o Hefesto procura um build `built` com
27
+ o mesmo commit: deste repositório, ou do repositório **de outro ambiente da app** com a mesma URL git,
28
+ branch, `build_path` e registry (só imagens no formato novo; a tag precisa continuar no registry).
29
+ Pergunta ao Ciclope o commit atual do branch (`git ls-remote`, sem clonar); bateu, **não builda**: a
30
+ etapa Build termina com "Imagem reaproveitada do build X do ambiente Y ..." e o Deploy implanta a mesma
31
+ imagem (vira uma linha `built` no repositório deste ambiente, para histórico e Redeploy). Falha na
32
+ consulta do commit nunca bloqueia: o build segue. Por isso o repositório de homol aponta para
33
+ `master`, como o de prod: deploy em homol e depois em prod do mesmo commit = um build só.
34
+ 2. **Versão**: o Hefesto lista as tags da app no registry (novas e antigas, de qualquer ambiente ou
35
+ instalação), pega a maior (somando as reservadas por builds em andamento dos outros ambientes) e
36
+ incrementa a parte escolhida (`major`, `minor`, `fix`, `test`), zerando as menores: `1.2.3.4` +
37
+ minor = `1.3.0.0`. Sem versão anterior parte de `0.0.0.0`. Registry fora do ar = o build não começa
38
+ (chutar a versão causaria colisão com outra instalação que compartilha o registry).
39
+ 3. **Clone**: branch do repositório, `--depth 1 --single-branch --no-tags`, credencial do conector
32
40
  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>`.
41
+ 4. **Build**: `podman build` (Buildah, não Docker) com `--jobs 2` (estágios independentes em
42
+ paralelo), no `build_path`, sempre com `--build-arg CONFIGURATION=production` (qualquer tipo e
43
+ ambiente; Dockerfile que não declara o `ARG` só ganha aviso). Para site: `--target site`.
35
44
  Limite padrão de 900 s; estourou = 504 com as últimas linhas da saída.
36
- 4. **Push** para `<registry>/<app_name>:<instalação>.<ambiente>-<versão>` (o prefixo é o
37
- `HEFESTO_INSTANCE_ID`; sem ele, `<ambiente>-<versão>` como antes). A imagem fica gravada na etapa Build
38
- da solicitação (`execution_image`), e é ela que o Deploy implanta.
39
- 5. **Retenção** (best-effort, nunca derruba o build): apaga as tags **desta instalação** do ambiente além
40
- das N mais novas (padrão 5), **exceto** as que algum worker está rodando. Tags de outros ambientes, de
41
- outras instalações que dividem o registry e tags antigas sem prefixo não são tocadas. Sem
42
- `HEFESTO_INSTANCE_ID`, a retenção fica desligada.
45
+ 5. **Push** para `<registry>/<app_name>:<versão>` (ex.: `app-exemplo:1.4.2.0`), sem ambiente nem prefixo
46
+ de instalação: a tag é da app, a mesma imagem serve todos os ambientes. A imagem fica gravada na etapa
47
+ Build da solicitação (`execution_image`), e é ela que o Deploy implanta.
48
+ 6. **Retenção** (best-effort, nunca derruba o build), **exceto** as tags que algum worker está rodando:
49
+ tags novas só com opt-in (`REGISTRY_PRUNE_SHARED_TAGS=true`: a tag é de todos os ambientes e
50
+ instalações), mantendo as N mais novas da app e as N mais novas de cada ambiente (padrão 5); tags
51
+ antigas (por ambiente) desta instalação além das N mais novas, como antes. Tags de outras
52
+ instalações nunca são tocadas.
43
53
 
44
54
  O cache do build fica no host do Ciclope (camadas + `--mount=type=cache`); imagens sem tag só são
45
55
  limpas depois de dias, para não perder o cache de quem builda com frequência. Por isso a ordem dos
@@ -53,8 +63,9 @@ limpas depois de dias, para não perder o cache de quem builda com frequência.
53
63
 
54
64
  Na etapa Deploy de uma solicitação **Deploy**, o Hefesto implanta **exatamente a imagem que o Build desta
55
65
  solicitação gravou** (e confere que ela ainda está no registry). Redeploy, sem Build, usa a versão mais nova
56
- publicada para o ambiente. O worker vai para `deploying` (com `deploying_since`) e o Hefesto chama o Talos do
57
- origin.
66
+ publicada para o ambiente (buildada ou promovida para ele). O worker vai para `deploying` (com `deploying_since`)
67
+ e o Hefesto chama o Talos do origin, dizendo o ambiente (`<ambiente>` = nome cadastrado em minúsculas): o front
68
+ escolhe o ambiente em runtime pelo `config.json`.
58
69
 
59
70
  ### service: rollout sem indisponibilidade
60
71
  1. `podman login` + `pull`;
@@ -68,7 +79,9 @@ origin.
68
79
  `-next`. Se a recriação falhar, a `-next` segue atendendo pelo alias e o resultado é `degraded` (um novo
69
80
  deploy normaliza);
70
81
  5. as variáveis do (app, ambiente) vão num arquivo com permissão 600, apagado logo depois do `run` — nunca como
71
- `-e K=V` no argv;
82
+ `-e K=V` no argv. O container recebe também `APP_ENV=<ambiente>` (se a app tem `APP_ENV` nas variáveis
83
+ dela, a dela vence; não é segredo nem conta como variável faltando). Service com UI: o servidor do app
84
+ serve o `config.json` da UI a partir de `brand/config/${APP_ENV}.json`;
72
85
  6. worker `running` com a tag; o Hefesto regenera o Caddyfile do origin.
73
86
 
74
87
  Consequências:
@@ -83,9 +96,13 @@ Consequências:
83
96
 
84
97
  ### site
85
98
  1. `pull`, `podman create` (o container nunca roda — por isso o `CMD ["unused"]` no estágio `site`);
86
- 2. copia `/dist/.` da imagem para uma pasta nova e troca o link da pasta do agent por rename atômico: se a cópia
87
- falhar, a versão anterior continua no ar;
88
- 3. Caddyfile regenerado: `file_server` na pasta, `uri strip_prefix <path>`, e `try_files {path}
99
+ 2. copia `/dist/.` da imagem para uma pasta nova; com `config_env=<ambiente>` (Talos ≥ 1.1.13), copia
100
+ `brand/config/<ambiente>.json` para `config.json` nessa pasta (sobrescreve um que viesse na imagem). Arquivo
101
+ ausente ou JSON inválido = `422`, a pasta nova é apagada e a versão anterior continua. Talos antigo ignora o
102
+ campo (o site sobe sem `config.json` e o front de produção não inicia). Imagem antiga, por ambiente, vai sem
103
+ `config_env` (já traz a configuração dela);
104
+ 3. troca o link da pasta do agent por rename atômico: se a cópia falhar, a versão anterior continua no ar;
105
+ 4. Caddyfile regenerado: `file_server` na pasta, `uri strip_prefix <path>`, e `try_files {path}
89
106
  /index.html` se `site_mode = spa`.
90
107
 
91
108
  ### Caddyfile
@@ -112,7 +129,9 @@ o server reiniciou durante a etapa X"), para alguém conferir o worker antes de
112
129
  ## Redeploy
113
130
 
114
131
  Solicitação **Redeploy** (Início → Deploy → Fim): o passo 3 sem build, com a última versão publicada do
115
- ambiente. Use para:
132
+ ambiente — a mais nova entre as tags que o repositório do ambiente buildou ou recebeu por promoção (e as antigas
133
+ do ambiente). Uma versão buildada para homol e ainda não promovida **não** vai para prod num Redeploy: promover
134
+ é um Deploy (cujo Build reaproveita a imagem) ou um Rollback para a versão escolhida. Use para:
116
135
  - aplicar variáveis de ambiente alteradas;
117
136
  - recriar um container que alguém parou ou removeu à mão;
118
137
  - publicar em um worker novo uma versão que já existe.
@@ -131,7 +150,9 @@ Regras:
131
150
  - migrations de banco **não** voltam. Versão antiga contra schema novo precisa ser compatível
132
151
  (migrations aditivas, nunca destrutivas no mesmo release);
133
152
  - o rollout com health check vale igual: se a versão antiga não subir saudável, a atual continua no ar;
134
- - site: o `/dist` da versão escolhida substitui o atual (troca atômica).
153
+ - site: o `/dist` da versão escolhida substitui o atual (troca atômica);
154
+ - versão antiga, por ambiente (`prod-1.3.0.0`, de antes da imagem única): funciona como antes — já foi buildada
155
+ com a configuração do ambiente, então o site vai sem `config_env` e o service ignora o `APP_ENV`.
135
156
 
136
157
  Todo deploy, redeploy e rollback de um worker fica no **histórico do worker** (aba Histórico da aplicação,
137
158
  `getWorkerHistory` no MCP), com a origem (solicitação, tela legada, MCP, API), as tags anterior e nova e o
@@ -146,6 +167,7 @@ resultado.
146
167
  | `fix` | correção |
147
168
  | `test` | build de teste/validação em ambiente não produtivo |
148
169
 
149
- A numeração é por ambiente: `homol-1.3.0.0` e `prod-1.3.0.0` são builds diferentes (branch e
150
- `CONFIGURATION` de cada ambiente; com `HEFESTO_INSTANCE_ID`, a tag ganha o prefixo da instalação, ex.:
151
- `hml1.homol-1.3.0.0`). Promover para produção = novo build no repositório de prod.
170
+ A numeração é da **app**, não do ambiente: `app-exemplo:1.3.0.0` é a mesma imagem em homol e prod.
171
+ Promover para produção = Deploy em prod do mesmo commit (o Build reaproveita a imagem; nada é buildado de
172
+ novo). Tags antigas por ambiente (`homol-1.3.0.0`, `<instalação>.prod-1.3.0.0`) continuam listadas e
173
+ implantáveis só no próprio ambiente; a primeira tag nova é sempre maior que todas elas.
@@ -10,8 +10,10 @@ Pedido típico: "faz o deploy do pedidos-api em homologação, sobe a minor".
10
10
  1. `listApps(search="pedidos")`: mais de uma parecida → pergunte qual.
11
11
  2. `getApp(app_id)`: ache o ambiente `homol`; mais de um worker → pergunte em qual (ou faça um por vez). Anote o
12
12
  `running_image_tag` do worker e o `repository_id` do ambiente.
13
- 3. `listBuilds(app_id, repository_id)`: última versão publicada (ex.: `homol-1.4.0.0`); a minor vai gerar a próxima
14
- (`homol-1.5.0.0`).
13
+ 3. `listBuilds(app_id, repository_id)`: última versão publicada (ex.: `1.4.0.0`); a minor vai gerar a próxima
14
+ (`1.5.0.0`). A tag é da app, sem ambiente: em prod, um Deploy do mesmo commit já publicado em homol
15
+ reaproveita a imagem (promoção, sem build), desde que os repositórios dos dois ambientes sejam a mesma fonte
16
+ (URL, branch, `build_path`, registry).
15
17
  4. Mostre ao usuário: aplicação, servidor/ambiente, versão em execução → versão nova. Confirme.
16
18
  5. `deployApp(app_id, worker_id, part="minor")` → `requested_id`.
17
19
  6. `getRequest(requested_id)` a cada poucos segundos até `finished=true`. O build costuma ser a etapa mais longa;