feat(ide): add browser VS Code for course notebooks

2026-10-18 22:39:39 +02:00
1 parent bf3241124c
commit 7d451a7ce9
@@ -96,7 +96,7 @@
 * snapshot/time travel на прикладном уровне;
 * базовый `compaction/vacuum` с параллелями к `Greenplum AppendOnly`;
 * набор практик в Jupyter Notebooks с обязательными заданиями и checkpoints;
-* стартовая документация до первого ноутбука: prerequisites, запуск стенда, вход в Jupyter и базовый troubleshooting.
+* стартовая документация до первого ноутбука: prerequisites, запуск стенда, вход в браузерный VS Code и базовый troubleshooting.

 Ориентировочная программа курса вынесена в отдельный документ: **[course_program.md](./course_program.md)**.

@@ -152,7 +152,7 @@

 **Acceptance Criteria для учебных материалов и результата:**

-1. В составе курса есть стартовая документация до первого ноутбука, включая prerequisites, запуск стенда, вход в `Jupyter` и получение учебного data bundle.
+1. В составе курса есть стартовая документация до первого ноутбука, включая prerequisites, запуск стенда, вход в браузерный VS Code и получение учебного data bundle.
 2. Студент проходит обязательные `checkpoints` по урокам.
 3. Студент самостоятельно выполняет набор практик на одном датасете, включая:
   * подключение к Spark и загрузку raw-данных;
@@ -174,7 +174,7 @@

 **В скоупе:**

-* использование существующего `docker-compose.yml` (`Spark`, `Trino`, `MinIO`, `PostgreSQL`, `Jupyter`);
+* использование существующего `docker-compose.yml` (`Spark`, `Trino`, `MinIO`, `PostgreSQL`, `code-server`, `JupyterLab`);
 * подготовка учебных датасетов и/или инструкций по их загрузке в репозиторий;
 * наличие воспроизводимого способа получить учебный data bundle без ручного поиска по внешним сайтам;
 * поддержка выполнения запросов к `Trino` из ноутбуков;
@@ -27,7 +27,7 @@

 ## 3. Состав учебных материалов

-Курс не должен состоять только из ноутбуков. Ноутбуки являются ядром практики, но вход в курс, запуск стенда и правила работы должны быть вынесены в обычную документацию, доступную до старта `Jupyter`.
+Курс не должен состоять только из ноутбуков. Ноутбуки являются ядром практики, но вход в курс, запуск стенда и правила работы должны быть вынесены в обычную документацию, доступную до открытия IDE.

 ### 3.1. Стартовая документация до первого ноутбука

@@ -38,7 +38,7 @@
 * `START_HERE.md` или аналогичный стартовый документ с маршрутом прохождения курса;
 * инструкция по prerequisites: `Docker`, `Docker Compose`, свободные порты, базовые команды;
 * пошаговый гайд по запуску стенда: `build`, `up`, проверка сервисов, открытие UI;
-* краткое объяснение, как пользоваться `Jupyter`, где лежат ноутбуки и как читать структуру урока;
+* краткое объяснение, как запускать Jupyter-ноутбуки в браузерном VS Code, где лежат ноутбуки и как читать структуру урока;
 * troubleshooting по типовым проблемам старта;
 * инструкция по reset/restart стенда для повторного прохождения практик.

@@ -46,7 +46,7 @@

 * студент понимает, что нужно установить и проверить до начала курса;
 * студент может поднять стенд без ментора;
-* студент знает, как попасть в `Jupyter`, `MinIO`, `Trino UI`;
+* студент знает, как попасть в браузерный VS Code, `MinIO`, `Trino UI`;
 * студент понимает, как устроен формат уроков и что от него ожидается.

 ### 3.2. Практическое ядро курса
@@ -88,7 +88,7 @@
 * запуск `docker compose build` и `docker compose up -d`;
 * проверка сервисов и веб-интерфейсов;
 * базовый smoke test для Spark;
-* первый обзор того, где в стенде `MinIO`, `PostgreSQL`, `Spark`, `Trino`, `Jupyter`.
+* первый обзор того, где в стенде `MinIO`, `PostgreSQL`, `Spark`, `Trino` и IDE.

 **Практика студента:**

@@ -17,7 +17,7 @@

 | Зона | Где лежит | Назначение |
 | --- | --- | --- |
-| Runtime / stand | `docker-compose.yml`, `spark/`, `trino/`, `jupyter/` | Топология сервисов, образы, конфиги, порты |
+| Runtime / stand | `docker-compose.yml`, `spark/`, `trino/`, `jupyter/`, `ide/`, `minio/` | Топология сервисов, образы, конфиги, порты |
 | 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/` | Конкретные runtime-конфиги и образы | Описание программы курса |
+| `spark/`, `trino/`, `jupyter/`, `ide/`, `minio/` | Конкретные runtime-конфиги и образы | Описание программы курса |
 | `README.md` | Верхнеуровневое объяснение репозитория, архитектуры и точек входа | Пошаговый student onboarding во всех деталях и low-level runtime reference |
 | `START_HERE.md` | Первый маршрут студента: prerequisites, запуск, первые UI, первый ноутбук, базовая диагностика | Полный PRD курса или подробный бэклог модулей |
 | `docs/stack_reference.md` | Технический reference стенда: сервисы, порты, доступ, reset, smoke-тесты | Роль основного onboarding-документа или описание всей программы курса |
@@ -15,7 +15,8 @@
 | MinIO API | `minio` | `9000` | S3-compatible endpoint |
 | MinIO Console | `minio` | `9001` | веб-консоль бакетов и объектов |
 | PostgreSQL | `postgres-iceberg` | `5432` | JDBC-каталог Iceberg |
-| JupyterLab | `jupyter` | `8888` | практические ноутбуки |
+| VS Code в браузере (code-server) | `ide` | `8889` | основной интерфейс для ноутбуков и терминала |
+| JupyterLab | `jupyter` | `8888` | запасной интерфейс для тех же ноутбуков |

 ## Основные команды

@@ -36,6 +37,7 @@ docker compose logs -f spark-master
 docker compose logs -f trino
 docker compose logs -f minio
 docker compose logs -f jupyter
+docker compose logs -f ide
 ```

 ### Остановка и reset
@@ -72,8 +74,7 @@ docker compose down -v
 Пример запуска smoke-скрипта:

 ```bash
-docker compose exec spark-master \
-  /opt/spark/bin/spark-submit /opt/src/spark/cluster_smoke.py
+docker compose exec ide python3 /opt/src/spark/cluster_smoke.py
 ```

 ### Trino
@@ -106,7 +107,13 @@ SHOW TABLES FROM lakehouse.default;
 - логин: `minioadmin`
 - пароль: `minioadmin`

-Стенд использует зафиксированные исторические образы MinIO Server и `mc` из официального namespace `quay.io/minio`. Эти версии подходят для локального курса, но больше не получают обновлений upstream и не предназначены для production.
+Стенд собирает 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.

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

@@ -126,6 +133,44 @@ psql -h localhost -p 5432 -U iceberg -d iceberg
 docker compose run --rm iceberg-catalog-init
 ```

+### VS Code в браузере
+
+Открой `http://localhost:8889`. Сервис `ide` запускает code-server с установленными
+расширениями Python и Jupyter. Python, ipykernel, Java, PySpark и зависимости курса
+уже находятся в образе. Локальный Python или venv не нужен.
+
+В рабочей области доступны ноутбуки, примеры из `src/` и документация. Репозиторий
+смонтирован в `/opt/course` только для чтения, а его каталог `notebooks/` — для
+чтения и записи. Так относительные ссылки между документами и ноутбуками работают
+и внутри IDE. Пути `/opt/work`, `/opt/src`, `/opt/data` также доступны примерам курса.
+Открой
+`01_environment_and_smoke_test.ipynb`, нажми **Select Kernel → Python Environments**
+и выбери `/usr/bin/python3`. Это Python внутри контейнера IDE. Расширение Jupyter
+запускает ядро там же; адрес отдельного Jupyter Server вводить не требуется.
+
+Порт IDE опубликован только на `127.0.0.1`, без пароля, для одного пользователя.
+Открывай именно `localhost` или `127.0.0.1`: браузер считает их доверенным
+контекстом даже по HTTP. Notebook webview использует service worker; при обращении
+по обычному HTTP к IP сервера или имени в локальной сети этот механизм может
+быть недоступен. Это ограничение secure context, отдельное от CORS и XSRF.
+См. [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts)
+и [webviews в code-server](https://coder.com/docs/code-server/FAQ#why-do-web-views-not-work).
+
+Для стенда на удалённой машине используй SSH-туннель:
+
+```bash
+ssh -N -L 8889:127.0.0.1:8889 user@host
+```
+
+Затем открой `http://localhost:8889` на своём компьютере. Прямой доступ по
+публичному адресу не входит в эту конфигурацию.
+
+Образы собираются в порядке `spark-master → jupyter → ide` через Compose
+`additional_contexts` (нужен Docker Compose 2.17+ и BuildKit). Версии code-server
+и расширений зафиксированы в `ide/Dockerfile`; расширения скачиваются при сборке.
+Автоматическое обновление расширений отключено, чтобы повторный запуск использовал
+проверенные версии.
+
 ### JupyterLab

 - адрес: `http://localhost:8888`
@@ -137,6 +182,10 @@ docker compose run --rm iceberg-catalog-init
 - `./data` смонтирован read-only как `/opt/data`
 - `PYTHONPATH=/opt/src`

+JupyterLab остаётся запасным интерфейсом. Он редактирует те же файлы, но запускает
+отдельные ядра: переменные Python между IDE и JupyterLab не общие. Перед сменой
+интерфейса сохрани ноутбук и останови его ядро.
+
 Первый ноутбук курса: `notebooks/01_environment_and_smoke_test.ipynb`.

 Для Модуля 3 локально скачанный data bundle должен лежать на хосте в `./data/nyc_taxi` и будет доступен внутри Jupyter по пути `/opt/data/nyc_taxi`.
@@ -159,14 +208,32 @@ docker compose run --rm iceberg-catalog-init
 | `trino/catalog/lakehouse.properties` | каталог Trino `lakehouse`, JDBC и S3-доступ |
 | `spark/Dockerfile` | образ Spark с Iceberg, S3A и Python-зависимостями |
 | `jupyter/Dockerfile` | образ JupyterLab на базе Spark |
+| `ide/Dockerfile` | code-server и расширения на базе образа Jupyter |
+| `ide/lakehouse.code-workspace` | папки рабочей области и настройки Python |
+| `minio/Dockerfile` | сборка закреплённых исходников MinIO Server и `mc` |

 ## Smoke-тесты

+### Браузерная IDE и Jupyter-ноутбук
+
+На Linux с Docker Engine, после запуска стенда:
+
+```bash
+bash tests/browser_ide.sh
+```
+
+Проверка запускает Chromium в отдельном контейнере и проходит путь студента:
+доверие рабочей области → открытие копии Модуля 1 → выбор Python → Run All →
+вывод Spark в webview → сохранение → повторное открытие. Затем проверяет, что
+все кодовые ячейки выполнились без ошибок и результат сохранился. Исходный
+ноутбук не меняется. Скриншот остаётся в каталоге `/tmp/lakehouse-browser-check.*`,
+путь печатается перед запуском. Docker Desktop этим скриптом не проверяется:
+он использует Linux host networking.
+
 ### 1. Проверка, что Spark-кластер жив

 ```bash
-docker compose exec spark-master \
-  /opt/spark/bin/spark-submit /opt/src/spark/cluster_smoke.py
+docker compose exec ide python3 /opt/src/spark/cluster_smoke.py
 ```

 ### 2. Проверка Spark -> Trino через общий каталог