diagrams and binaries

docs/SETUP.md

@@ -1,16 +1,21 @@
 # Подготовка стенда и первичная инициализация
 
-Документ описывает, как собрать компоненты, подготовить конфигурацию и
-запустить стенд с нуля — от чистой машины до работающего control-api,
-валидаторов и проберов. Если нужно просто быстро посмотреть систему в
-работе без реального OpenStack — сразу переходите к разделу
+Документ описывает, как подготовить конфигурацию и запустить стенд с нуля
+— от чистой машины до работающего control-api, валидаторов и проберов.
+Бинарники брать не обязательно из исходников: в репозитории уже лежат
+готовые сборки для Linux x86_64 (`bin/`) — это самый быстрый путь к
+развёртыванию, см. [«Получение бинарников»](#получение-бинарников). Если
+нужно просто быстро посмотреть систему в работе без реального OpenStack —
+сразу переходите к разделу
 [«Быстрая проверка без OpenStack»](#быстрая-проверка-без-openstack-offline-режим).
 
 ## Содержание
 
 - [Компоненты и роли машин](#компоненты-и-роли-машин)
 - [Требования](#требования)
-- [Сборка бинарников](#сборка-бинарников)
+- [Получение бинарников](#получение-бинарников)
+  - [Вариант A: готовые бинарники из репозитория (рекомендуется)](#вариант-a-готовые-бинарники-из-репозитория-рекомендуется)
+  - [Вариант B: сборка из исходников](#вариант-b-сборка-из-исходников)
 - [Быстрая проверка без OpenStack (offline-режим)](#быстрая-проверка-без-openstack-offline-режим)
 - [Подготовка конфигурации для реального стенда](#подготовка-конфигурации-для-реального-стенда)
 - [Развёртывание control-api](#развёртывание-control-api)
@@ -33,9 +38,12 @@ control-api (см. [API.md](API.md)).
 
 ## Требования
 
-- **Go 1.22+** для сборки (проверено на Go 1.26). Собранные бинарники —
-  статические, дополнительных зависимостей на целевых машинах не требуют
-  (используется чистый Go-драйвер SQLite, без cgo).
+- Целевые серверы (control-api, валидаторы, площадки) — **Linux
+  x86_64 (amd64)**. Для этой платформы в репозитории уже лежат готовые
+  бинарники (см. ниже) — устанавливать Go на целевые машины не требуется.
+- **Go 1.22+** нужен только если вы пересобираете бинарники из
+  исходников (проверено на Go 1.26) — например, для другой платформы
+  (arm64, другая ОС) или после изменения кода.
 - Для `control-api` в боевом режиме (`openstack.mode: real`) — учётная
   запись OpenStack с правами на чтение/изменение floating IP (Neutron)
   в сервисном проекте, и заранее выделенные (allocated) floating IP —
@@ -46,15 +54,65 @@ control-api (см. [API.md](API.md)).
 - `curl`, `sqlite3` (опционально, для ручной инспекции БД) на машине с
   control-api пригодятся для диагностики.
 
-## Сборка бинарников
+## Получение бинарников
+
+### Вариант A: готовые бинарники из репозитория (рекомендуется)
+
+В директории `bin/` репозитория уже лежат три готовых бинарника —
+собирать их на целевых серверах не нужно, разворачивание сразу
+начинается с копирования и запуска (раздел
+[«Развёртывание control-api»](#развёртывание-control-api) и далее).
+
+```
+bin/
+├── control-api        # ~11 МБ
+├── validator-agent     # ~7 МБ
+├── prober               # ~7 МБ
+└── SHA256SUMS
+```
+
+Характеристики сборки:
+- Платформа: `GOOS=linux GOARCH=amd64`.
+- `CGO_ENABLED=0` — статическая линковка, без cgo (используется чистый
+  Go-драйвер SQLite `modernc.org/sqlite`). Дополнительные `.so`-библиотеки
+  и конкретная версия glibc на целевом сервере **не требуются**.
+- Собрано флагами `-trimpath -ldflags="-s -w"` (без путей сборки и
+  отладочной информации — компактнее и без утечки информации о машине
+  сборки).
+
+Убедиться в отсутствии динамических зависимостей и целостности файлов
+после переноса на целевой сервер:
+
+```bash
+ldd bin/control-api   # => "not a dynamic executable"
+file bin/control-api  # => ELF 64-bit LSB executable, x86-64, statically linked
+
+# После scp/rsync на целевой сервер — проверить, что файлы не повреждены:
+sha256sum -c bin/SHA256SUMS
+```
+
+Перенос на целевые серверы, например:
+
+```bash
+scp bin/control-api     control-api-host:/tmp/
+scp bin/validator-agent validator-host-01:/tmp/
+scp bin/prober           probe-site-1:/tmp/
+```
+
+> Если целевая платформа отличается от linux/amd64 (например, ВМ на
+> arm64) — готовые бинарники не подойдут, используйте
+> [вариант B](#вариант-b-сборка-из-исходников).
+
+### Вариант B: сборка из исходников
 
 Из корня репозитория:
 
 ```bash
 export PATH=$PATH:/usr/local/go/bin   # если go не в PATH
-go build -o bin/control-api     ./cmd/control-api
-go build -o bin/validator-agent ./cmd/validator-agent
-go build -o bin/prober          ./cmd/prober
+export CGO_ENABLED=0 GOOS=linux GOARCH=amd64   # поменяйте GOARCH для другой платформы
+go build -trimpath -ldflags="-s -w" -o bin/control-api     ./cmd/control-api
+go build -trimpath -ldflags="-s -w" -o bin/validator-agent ./cmd/validator-agent
+go build -trimpath -ldflags="-s -w" -o bin/prober          ./cmd/prober
 ```
 
 Каждый бинарник самодостаточен — скопируйте нужный файл на
@@ -67,6 +125,14 @@ go build -o bin/prober          ./cmd/prober
 go build ./... && go test ./...
 ```
 
+Пересобирайте из исходников и обновляйте `bin/` с зафиксированными
+`SHA256SUMS`, если меняли код — готовые бинарники в репозитории **не
+обновляются автоматически**:
+
+```bash
+sha256sum bin/control-api bin/validator-agent bin/prober | sed 's#bin/##' > bin/SHA256SUMS
+```
+
 ## Быстрая проверка без OpenStack (offline-режим)
 
 Прежде чем разворачивать реальный стенд, рекомендуется убедиться, что всё