fix(stack): use pinned MinIO image with registry fallback

2026-10-19 09:26:12 +02:00
1 parent 7d451a7ce9
commit 78cf7b5fae
@@ -17,7 +17,7 @@

 | Зона | Где лежит | Назначение |
 | --- | --- | --- |
-| Runtime / stand | `docker-compose.yml`, `spark/`, `trino/`, `jupyter/`, `ide/`, `minio/` | Топология сервисов, образы, конфиги, порты |
+| Runtime / stand | `docker-compose.yml`, `spark/`, `trino/`, `jupyter/`, `ide/` | Топология сервисов, образы, конфиги, порты |
 | Onboarding | `README.md`, `START_HERE.md` | Вход в репозиторий и первый пользовательский маршрут |
 | Runtime reference | `docs/stack_reference.md` | Технические детали стенда: порты, доступ, команды, smoke-тесты |
 | Course definition | `docs/course_prd.md`, `docs/course_program.md` | Границы курса, learning outcomes, структура модулей |
@@ -31,7 +31,7 @@
 | Файл или каталог | За что отвечает | Что не стоит туда складывать |
 | --- | --- | --- |
 | `docker-compose.yml` | Реальный состав сервисов, контейнеров, сетей, портов и зависимостей | Учебные пояснения, которые не нужны для запуска |
-| `spark/`, `trino/`, `jupyter/`, `ide/`, `minio/` | Конкретные runtime-конфиги и образы | Описание программы курса |
+| `spark/`, `trino/`, `jupyter/`, `ide/` | Конкретные runtime-конфиги и образы | Описание программы курса |
 | `README.md` | Верхнеуровневое объяснение репозитория, архитектуры и точек входа | Пошаговый student onboarding во всех деталях и low-level runtime reference |
 | `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей |
 | `docs/stack_reference.md` | Технический reference стенда: сервисы, порты, доступ, reset, smoke-тесты | Роль основного onboarding-документа или описание всей программы курса |
@@ -34,8 +34,8 @@

 ### Модуль 1. Вход в стенд

- **Docker не хватает ресурсов.** Стенд требует ~4-6 ГБ RAM. На машинах с 8 ГБ бывают проблемы. Решение: увеличить лимиты Docker Desktop или закрыть лишние приложения.
- **Порты заняты.** 8080, 8888, 9000 — популярные порты. `docker compose ps` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`.
+- **Docker не хватает ресурсов.** Сверься с [требованиями в START_HERE](../START_HERE.md#prerequisites). Проверь отдельно память компьютера и лимит памяти Docker Desktop/WSL2: контейнерам может быть доступна лишь часть RAM хоста.
+- **Порты заняты.** Проверь 8080, 8889, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`.
 - **Студент не читает `START_HERE.md`.** Начинает с ноутбуков до поднятия стенда. Направь обратно к стартовому документу.

 ### Модуль 2. Ментальная модель
@@ -0,0 +1,74 @@
+# Если образы или зависимости не скачиваются
+
+Доступность репозиториев зависит от сети и провайдера, в том числе в РФ.
+GHCR выбран основным источником MinIO, чтобы его загрузка не зависела от Docker
+Hub. Это не гарантия доступности без VPN у каждого провайдера: у стенда остаются
+другие внешние зависимости. Для первой сборки и скачивания датасета нужен интернет.
+
+## Сначала найди источник ошибки
+
+Запускай команды в терминале хоста, из корня репозитория:
+
+```bash
+docker compose pull minio minio-init postgres trino
+docker compose --progress plain build
+```
+
+Если первая команда завершилась с ошибкой, сначала реши проблему загрузки образа.
+Если ошибка возникла во второй, найди имя сервиса и адрес, с которого скачивался
+файл. Открывающийся в браузере сайт ещё не подтверждает доступ из Docker.
+
+| Где возникла ошибка | Что скачивается | Что проверить |
+| --- | --- | --- |
+| `ghcr.io` при загрузке `minio` | Готовые MinIO и `mc` | Резервный источник ниже |
+| `docker.io`, `registry-1.docker.io`, `auth.docker.io` | PostgreSQL, Trino, базовый Spark; резерв MinIO | Доступ Docker к Docker Hub и настройки прокси |
+| Ubuntu archive, PyPI, Maven Central при сборке `spark` или `jupyter` | Системные пакеты, Python-пакеты и JAR | Доступ к зависимостям из сборки |
+| GitHub Releases, Open VSX при сборке `ide` | code-server и расширения | Доступ к зависимостям из сборки |
+
+## Резервный источник MinIO
+
+Автор образа публикует его в двух местах: GHCR и Docker Hub. В обоих закреплён
+один digest, поэтому смена registry не меняет версию или содержимое образа.
+Ссылка на сборку и версия приведены в [техническом reference](./stack_reference.md#minio).
+
+Если GHCR недоступен, создай файл `.env` в корне репозитория и добавь строку:
+
+```dotenv
+MINIO_REGISTRY=docker.io
+```
+
+Если файл уже существует, измени только эту настройку. Другие значения, например
+`NB_UID` и `NB_GID`, сохрани. Затем повтори:
+
+```bash
+docker compose pull minio minio-init
+```
+
+Дальше используй обычные команды из [START_HERE](../START_HERE.md#быстрый-запуск).
+Для возврата к основному источнику установи `MINIO_REGISTRY=ghcr.io`.
+Оба источника публичные; регистрация для скачивания MinIO не требуется.
+`.env.example` содержит пример настроек, а `.env` исключён из Git.
+
+## Если недоступны другие источники
+
+Переключение MinIO не меняет источник PostgreSQL, Trino, Spark или зависимостей
+сборки. Если в твоей сети нужен VPN или HTTP-прокси, важно, чтобы им мог
+пользоваться Docker, а не только браузер.
+
+- **Docker Desktop:** настрой прокси в разделе **Settings → Resources → Proxies**.
+  См. [официальную инструкцию](https://docs.docker.com/desktop/settings-and-maintenance/settings/#proxies).
+- **Docker Engine на Linux:** скачиванием образов занимается демон Docker.
+  Для него есть [отдельная настройка прокси](https://docs.docker.com/engine/daemon/proxy/).
+- **Команды внутри сборки:** `apt`, `pip`, `curl` и установка расширений требуют
+  доступа из build-контейнера. Docker описывает
+  [настройки прокси для сборок](https://docs.docker.com/engine/cli/proxy/#build-with-a-proxy-configuration)
+  отдельно от настроек демона. Прокси на `localhost` хоста не обязательно
+  доступен как `localhost` внутри контейнера.
+
+Ошибка `429` обычно означает лимит запросов, а `401`/`403` может быть связана
+с доступом к registry. Сам по себе этот код не доказывает блокировку по стране.
+Не меняй версии образов и не удаляй данные стенда для исправления сетевой ошибки.
+
+Если нужна помощь, передай ментору ОС, вывод `docker compose version`, команду,
+имя сервиса и фрагмент ошибки с адресом источника. Пароли и адреса прокси
+с учётными данными в сообщение не добавляй.
@@ -107,13 +107,20 @@ SHOW TABLES FROM lakehouse.default;
 - логин: `minioadmin`
 - пароль: `minioadmin`

-Стенд собирает MinIO Server `RELEASE.2024-10-02T17-50-41Z` и `mc`
-`RELEASE.2024-06-24T19-40-33Z` из официальных исходников. Коммиты и SHA-256 архивов
-зафиксированы в `minio/Dockerfile`. Готовые образы этих версий в Docker Hub и Quay
-больше не загружаются; бинарный архив `dl.min.io` также недоступен.
-Первая сборка компилирует Go-код и занимает несколько дополнительных минут.
-Версии сохранены ради совместимости с курсом и его MinIO Console; они больше
-не получают обновлений upstream и не предназначены для production.
+Стенд использует готовый образ `coollabsio/minio:RELEASE.2025-04-22T22-12-26Z`.
+Это сторонняя [сборка из официальных исходников MinIO](https://github.com/coollabsio/minio),
+которая содержит сервер и клиент `mc` версии `RELEASE.2025-08-13T08-35-41Z`.
+Версия сервера предшествует [изменению встроенной консоли в мае 2025 года](https://github.com/minio/minio/releases/tag/RELEASE.2025-05-24T17-08-30Z).
+Образ подходит для локального курса; это историческая
+версия без текущих обновлений, не production-конфигурация.
+
+В Compose закреплён digest индекса для AMD64 и ARM64:
+`sha256:a4938f37f1be1841b8e7b627ad0207b265345fd0d063e42d7410c78af0e63e68`.
+Сервисы `minio` и `minio-init` используют один образ. Компиляция MinIO и установка
+Go не нужны. По умолчанию образ скачивается из GHCR без авторизации. Автор
+публикует тот же digest в Docker Hub; резервный источник выбирается через
+`MINIO_REGISTRY=docker.io` в `.env`. Подробности — в
+[инструкции по доступу к репозиториям](./network_access.md).

 Бакет `lakehouse` обычно создаётся автоматически контейнером `minio-init`.

@@ -210,7 +217,7 @@ JupyterLab остаётся запасным интерфейсом. Он ред
 | `jupyter/Dockerfile` | образ JupyterLab на базе Spark |
 | `ide/Dockerfile` | code-server и расширения на базе образа Jupyter |
 | `ide/lakehouse.code-workspace` | папки рабочей области и настройки Python |
-| `minio/Dockerfile` | сборка закреплённых исходников MinIO Server и `mc` |
+| `docs/network_access.md` | источники образов и зависимостей, резервный registry и диагностика сети |

 ## Smoke-тесты

@@ -230,6 +237,9 @@ bash tests/browser_ide.sh
 путь печатается перед запуском. Docker Desktop этим скриптом не проверяется:
 он использует Linux host networking.

+Для проверки отдельного стенда можно задать `COMPOSE_FILE` и `IDE_URL`; по
+умолчанию тест использует текущий Compose-проект и `http://localhost:8889`.
+
 ### 1. Проверка, что Spark-кластер жив

 ```bash