Files
crank/_bmad-output/implementation-artifacts/spec-ci-debian-apt-https-bootstrap.md
T

80 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: 'Исправить runtime Docker build при недоступном Debian HTTP mirror'
type: 'bugfix'
created: '2026-08-29'
status: 'done'
baseline_commit: '55209a9bbc38f7a34c972cba5d9fad27bc9305b0'
review_loop_iteration: 0
context: []
---
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
## Intent
**Problem:** Release build успешно компилирует Rust binaries, но runtime-слой `debian:bookworm-slim` обращается к `deb.debian.org` по HTTP/80. В CI этот порт недоступен, поэтому `apt-get update` оставляет пустые indexes и установка `ca-certificates curl` завершается ошибкой.
**Approach:** Перевести Debian repositories обоих Rust runtime images на HTTPS, предварительно bootstrap-ить доверенный CA bundle из уже используемого Rust builder image, и добавить ограниченные apt retries для кратковременных сетевых сбоев.
## Boundaries & Constraints
**Always:** Одинаково исправить `admin-api` и `mcp-server`; TLS verification остаётся включённой; runtime сохраняет `ca-certificates` для исходящих HTTPS-запросов и `curl` для существующих Compose healthchecks; Docker build остаётся воспроизводимым в текущем multi-stage layout.
**Ask First:** Смена runtime base image, удаление `curl`/healthchecks, добавление нового healthcheck binary или изменение release workflow.
**Never:** `Acquire::https::Verify-Peer=false`, trusted/unsigned repositories, fallback на HTTP, бесконечные retry loops или игнорирование ненулевого exit code `apt-get`.
## I/O & Edge-Case Matrix
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|----------|---------------|---------------------------|----------------|
| HTTP/80 недоступен | Registry доступен, Debian mirror доступен только по HTTPS/443 | Оба runtime images собираются через HTTPS repositories | Build падает, если HTTPS или signature verification реально не проходят |
| Чистый slim runtime | В runtime layer ещё нет `ca-certificates` package | CA bundle из builder позволяет проверить TLS первого `apt-get update` | Нельзя отключать TLS verification для bootstrap |
| Кратковременный mirror failure | HTTPS request временно не проходит | APT выполняет конечное число повторов | После исчерпания retries build завершается ошибкой |
| Runtime contract | Image успешно собран | CA bundle непустой, `curl` установлен, application entrypoint/CMD сохранены | Contract check не запускает сервис и не меняет production state |
</frozen-after-approval>
## Code Map
- `apps/admin-api/Dockerfile:17-23` — runtime stage устанавливает CA/curl; builder уже содержит `/etc/ssl/certs/ca-certificates.crt`.
- `apps/mcp-server/Dockerfile:54-60` — тот же runtime bootstrap и источник текущего CI failure на строке 56.
- `docker-compose.yml:130,193` — healthchecks зависят от `curl` внутри images.
- `deploy/community/docker-compose.yml:144,205` и `deploy/community/docker-compose.images.yml:141,202` — packaged community healthchecks подтверждают, что `curl` нельзя удалить локальным workaround.
- `.gitea/workflows/ci.yml:267-268,371-375` и `.gitea/workflows/release.yml:197-202` — оба Dockerfile собираются в CI/release; workflow менять не требуется.
## Tasks & Acceptance
**Execution:**
- [x] `apps/admin-api/Dockerfile` — скопировать CA bundle из builder до первого HTTPS request, переключить Debian sources на HTTPS и включить bounded retries.
- [x] `apps/mcp-server/Dockerfile` — применить идентичный runtime bootstrap, не меняя binary build/CMD.
- [x] Docker verification — собрать оба images и проверить наличие CA bundle/curl внутри runtime layers.
**Acceptance Criteria:**
- Given исходный CI network profile с недоступным HTTP/80 и доступным HTTPS/443, when собираются `admin-api` и `mcp-server`, then оба builds завершаются успешно без ослабления TLS или repository signature verification.
- Given собранные images, when проверяется runtime contract, then `curl` доступен, CA bundle непустой, а исходные ENTRYPOINT/CMD остаются неизменными.
## Spec Change Log
## Design Notes
CA bootstrap берётся из `rust:1.96.1-bookworm`, уже являющегося доверенной build stage на той же Debian-family базе. После HTTPS `apt-get update` пакет `ca-certificates` устанавливается штатно и становится владельцем актуального runtime trust store.
## Verification
**Commands:**
- `docker build --progress=plain -f apps/admin-api/Dockerfile -t crank/admin-api:ci-fix .` — passed; runtime APT получил подписанные indexes через HTTPS и установил `ca-certificates`/`curl`.
- `docker build --progress=plain -f apps/mcp-server/Dockerfile -t crank/mcp-server:ci-fix .` — passed.
- `docker run --rm --entrypoint sh crank/admin-api:ci-fix -c 'test -s /etc/ssl/certs/ca-certificates.crt && curl --version >/dev/null'` — passed.
- `docker run --rm --entrypoint sh crank/mcp-server:ci-fix -c 'test -s /etc/ssl/certs/ca-certificates.crt && curl --version >/dev/null'` — passed.
- `docker image inspect ...` — passed; admin image сохранил `ENTRYPOINT [\"/usr/local/bin/crank-admin-entrypoint\"]` и `CMD [\"admin-api\"]`, MCP image сохранил `CMD [\"mcp-server\"]`.
- `git diff --check` — passed.
## Suggested Review Order
- Основной runtime bootstrap: доверенный CA, HTTPS-only sources и ограниченные повторы APT.
[`admin-api/Dockerfile:19`](../../apps/admin-api/Dockerfile#L19)
- Тот же защищённый bootstrap применён к MCP runtime без изменения команды запуска.
[`mcp-server/Dockerfile:56`](../../apps/mcp-server/Dockerfile#L56)