From db8f275ea070cca3e0d22a973408cf8c28aa6598 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Wed, 21 Oct 2026 10:22:00 +0200 Subject: [PATCH] docs(course): make JupyterLab the primary notebook interface --- README.md | 18 ++-- START_HERE.md | 49 +++++----- docs/course_prd.md | 7 +- docs/course_program.md | 9 +- docs/mentor_notes.md | 2 +- docs/stack_reference.md | 90 +++++++++++++------ docs/study_workflow.md | 39 ++++---- notebooks/01_environment_and_smoke_test.ipynb | 12 +-- 8 files changed, 138 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index a638adf..8545ae3 100755 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ graph TB U[Student / engineer] subgraph Access - J[VS Code в браузере
Jupyter notebooks / PySpark] + J[JupyterLab
Notebooks / PySpark] Q[Trino UI / CLI
ad hoc SQL] end @@ -55,8 +55,8 @@ graph TB | `PostgreSQL` | Catalog — метаданные JDBC-каталога `lakehouse` | | `Spark` | Compute — ETL, запись и чтение Iceberg-таблиц | | `Trino` | Compute — ad hoc SQL, чтение тех же таблиц | -| `code-server` | VS Code в браузере — ноутбуки курса, Python и терминал внутри Docker | -| `JupyterLab` | Запасной интерфейс для тех же ноутбуков | +| `JupyterLab` | Основной интерфейс — ноутбуки курса, Python и терминал внутри Docker | +| `code-server` | VS Code в браузере — альтернативный интерфейс для тех же ноутбуков | Ноутбуки подключаются к Spark-кластеру с [готовыми настройками стенда](./docs/stack_reference.md#spark). @@ -91,16 +91,20 @@ MinIO скачивается готовым из GHCR, его версия и di | UI | Адрес | | --- | --- | -| VS Code в браузере | `http://localhost:8889` | -| JupyterLab (запасной интерфейс) | `http://localhost:8888` | +| JupyterLab | `http://localhost:8888` | +| VS Code в браузере (по желанию) | `http://localhost:8889` | | Spark Master | `http://localhost:8080` | | Trino | `http://localhost:8090` | | MinIO Console | `http://localhost:9001` | -Открой ноутбук в браузерном VS Code и выбери Python внутри контейнера: локальный -Python и venv не нужны. Оба интерфейса доступны только с хоста стенда. +Открой ноутбук в JupyterLab: Python работает внутри контейнера, локальный +Python и venv не нужны. JupyterLab доступен только с хоста стенда. Первый запуск ноутбука описан в [START_HERE.md](./START_HERE.md#как-работать-с-ноутбуками). +VS Code запускается вместе со стендом. Его можно использовать по желанию; +он совместим не со всеми сочетаниями браузера, расширений и средств защиты. +[Выбор ядра и доступ к удалённому стенду](./docs/stack_reference.md#vs-code-в-браузере). + ## Документы для прохождения - [START_HERE.md](./START_HERE.md) — подготовка компьютера, запуск и первый результат. diff --git a/START_HERE.md b/START_HERE.md index a9e8514..be37958 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -12,7 +12,7 @@ 1. Подготовь Docker, ресурсы и локальную копию репозитория. 2. Скачай образы, собери окружение и проверь запуск сервисов. -3. Открой первый ноутбук в браузерном VS Code и проверь результат вычисления. +3. Открой первый ноутбук в JupyterLab и проверь результат вычисления. 4. Продолжи по [программе курса](./docs/course_program.md#маршрут-по-модулям). Датасет Taxi понадобится перед Модулем 3, DBeaver необязателен и понадобится @@ -23,13 +23,13 @@ ## Что подготовить - Docker с запущенным движком и Docker Compose 2.17+ с BuildKit. -- Современный браузер; основной интерфейс курса — VS Code на `localhost:8889`. +- Современный браузер; основной интерфейс курса — JupyterLab на `localhost:8888`. - Git для скачивания репозитория или его распакованную ZIP-копию. - Свободные порты из таблицы ниже и доступ к источникам образов и зависимостей. Команды ниже рассчитаны на Bash: терминал Linux/macOS или терминал Linux в WSL2 на Windows с включенной интеграцией Docker Desktop. Выполняй их на -машине, где работает Docker. Терминал внутри браузерного VS Code для запуска +машине, где работает Docker. Терминал внутри JupyterLab для запуска `docker compose` не подходит. ### Системные требования @@ -94,8 +94,8 @@ docker compose config --quiet | Trino UI | `http://localhost:8090` | Проверка координатора Trino | | MinIO API | `http://localhost:9000` | S3-compatible endpoint | | MinIO Console | `http://localhost:9001` | Просмотр бакетов и файлов | -| VS Code в браузере | `http://localhost:8889` | Основная точка входа в практику | -| JupyterLab | `http://localhost:8888` | Запасной интерфейс для ноутбуков | +| JupyterLab | `http://localhost:8888` | Основная точка входа в практику | +| VS Code в браузере | `http://localhost:8889` | Альтернативный интерфейс, по желанию | | PostgreSQL | `localhost:5432` | JDBC-каталог Iceberg, нужен для диагностики | ## Быстрый запуск @@ -165,15 +165,15 @@ docker compose ps -a | --- | --- | | [Spark Master](http://localhost:8080) | Два worker-а в состоянии `ALIVE` | | [MinIO Console](http://localhost:9001) | После входа `minioadmin` / `minioadmin` виден бакет `lakehouse` — контейнер для файлов курса | -| [VS Code](http://localhost:8889) | Слева папки **Ноутбуки**, **Примеры (только чтение)**, **Документация (только чтение)** | +| [JupyterLab](http://localhost:8888) | Слева список ноутбуков `01_…` — `08_…` | В [Trino UI](http://localhost:8090) для входа достаточно имени, например `student`; пароль в стенде не задан. Сейчас достаточно проверить, что интерфейс открывается. Чтение общих таблиц через Trino разберем в Модуле 6. Этот маршрут предполагает Docker на твоем компьютере: `localhost` относится -к машине с браузером. Доступ к VS Code на удаленном сервере описан отдельно -в [инструкции по SSH-туннелю](./docs/stack_reference.md#vs-code-в-браузере). +к машине с браузером. Доступ к JupyterLab на удаленном сервере описан отдельно +в [инструкции по SSH-туннелю](./docs/stack_reference.md#jupyterlab). ## Роли сервисов в стенде @@ -183,26 +183,23 @@ docker compose ps -a | `PostgreSQL` | `catalog`: хранит метаданные JDBC-каталога Iceberg | | `Spark` | `compute`: выполняет PySpark и Spark SQL задания | | `Trino` | `compute`: читает те же таблицы через общий каталог | -| `VS Code / JupyterLab` | Интерфейсы для учебных ноутбуков | +| `JupyterLab` | Интерфейс для учебных ноутбуков | ## Как работать с ноутбуками Ноутбук — файл с пояснениями, кодом и сохраненным выводом. Ядро — процесс Python, который исполняет код и хранит переменные до остановки. -1. Открой `http://localhost:8889` в отдельной вкладке браузера. -2. Если сверху виден **Restricted Mode**, нажми **Manage → Trust** и закрой окно - Workspace Trust. Подтверди доверие только к своей копии этого учебного - репозитория: в Restricted Mode запуск ноутбуков ограничен. -3. В папке **Ноутбуки** открой `01_environment_and_smoke_test.ipynb`. -4. Нажми **Select Kernel → Python Environments** и выбери Python с путём - `/usr/bin/python3`. Он находится внутри контейнера `ide`, где уже есть - зависимости курса. Пункт **Existing Jupyter Server** здесь не нужен. -5. Запусти первую кодовую ячейку кнопкой слева или `Shift+Enter`, затем остальные +1. Открой `http://localhost:8888` в отдельной вкладке браузера. +2. Дважды нажми на `01_environment_and_smoke_test.ipynb` в списке файлов слева. +3. Если появится выбор ядра, выбери **Python 3 (ipykernel)**. Изменить ядро можно + через **Kernel → Change Kernel…**. Оно работает внутри контейнера `jupyter`, + где уже есть зависимости курса. Дождись состояния **Idle** в нижней панели. +4. Выдели первую кодовую ячейку и запусти её через `Shift+Enter`, затем остальные ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через - **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`). + **File → Save Notebook** (`Ctrl+S`; на macOS — `Cmd+S`). -Терминал VS Code тоже работает внутри контейнера. Команды `docker compose` +Терминал JupyterLab тоже работает внутри контейнера. Команды `docker compose` выполняй в терминале хоста, откуда запускал стенд. ### Как понять, что первый запуск прошел @@ -228,17 +225,19 @@ expected_sum=499999500000 Правила запуска ячеек, перехода между модулями и сохранения данных собраны в [памятке учащегося](./docs/study_workflow.md). -Запасной интерфейс — JupyterLab на `http://localhost:8888`. Файлы ноутбуков общие, -а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и заверши -Spark-сессию через `spark.stop()`; не редактируй один файл в двух интерфейсах -одновременно. +По желанию можно работать в [VS Code на `localhost:8889`](./docs/stack_reference.md#vs-code-в-браузере): +он запускается вместе со стендом. Некоторые сочетания браузера, расширений и +средств защиты мешают открытию ноутбуков в VS Code. В таком случае продолжи +курс в JupyterLab. Файлы общие, а ядра Python отдельные: перед сменой интерфейса +сохрани ноутбук, выполни `spark.stop()` и останови ядро. Не редактируй один файл +в двух интерфейсах одновременно. ## Базовая диагностика Начни с `docker compose ps -a` и логов проблемного сервиса, например: ```bash -docker compose logs --tail=100 ide +docker compose logs --tail=100 jupyter ``` Выбери свой симптом в [таблице диагностики](./docs/study_workflow.md#если-что-то-не-работает). diff --git a/docs/course_prd.md b/docs/course_prd.md index c9a0024..df06d39 100644 --- a/docs/course_prd.md +++ b/docs/course_prd.md @@ -96,7 +96,7 @@ * snapshot/time travel на прикладном уровне; * базовый `compaction/vacuum` с параллелями к `Greenplum AppendOnly`; * набор практик в Jupyter Notebooks с обязательными заданиями и checkpoints; -* стартовая документация до первого ноутбука: prerequisites, запуск стенда, вход в браузерный VS Code и базовый troubleshooting. +* стартовая документация до первого ноутбука: prerequisites, запуск стенда, вход в JupyterLab и базовый troubleshooting. Ориентировочная программа курса вынесена в отдельный документ: **[course_program.md](./course_program.md)**. @@ -152,7 +152,7 @@ **Acceptance Criteria для учебных материалов и результата:** -1. В составе курса есть стартовая документация до первого ноутбука, включая prerequisites, запуск стенда, вход в браузерный VS Code и получение учебного data bundle. +1. В составе курса есть стартовая документация до первого ноутбука, включая prerequisites, запуск стенда, вход в JupyterLab и получение учебного data bundle. 2. Студент проходит обязательные `checkpoints` по урокам. 3. Студент самостоятельно выполняет набор практик на одном датасете, включая: * подключение к Spark и загрузку raw-данных; @@ -174,7 +174,8 @@ **В скоупе:** -* использование существующего `docker-compose.yml` (`Spark`, `Trino`, `MinIO`, `PostgreSQL`, `code-server`, `JupyterLab`); +* использование существующего `docker-compose.yml` (`Spark`, `Trino`, `MinIO`, `PostgreSQL`, `JupyterLab`, `code-server`); +* JupyterLab как основной интерфейс курса; браузерный VS Code доступен в том же стенде по желанию, с учётом совместимости браузера и средств защиты на компьютере; * подготовка учебных датасетов и/или инструкций по их загрузке в репозиторий; * наличие воспроизводимого способа получить учебный data bundle без ручного поиска по внешним сайтам; * поддержка выполнения запросов к `Trino` из ноутбуков; diff --git a/docs/course_program.md b/docs/course_program.md index 6f9802c..4538d62 100644 --- a/docs/course_program.md +++ b/docs/course_program.md @@ -25,6 +25,11 @@ самопроверки. Сохраненный вывод помогает вернуться к результату, но не заменяет собственный запуск и объяснение. +Основной интерфейс курса — JupyterLab. В том же стенде доступен +[VS Code в браузере](./stack_reference.md#vs-code-в-браузере), если тебе удобнее +работать в нём. Совместимость зависит от браузера, расширений и средств защиты +на компьютере; оба интерфейса открывают одни и те же ноутбуки. + ## 1. Рамка курса **Формат:** стартовая документация + 8 практических уроков в `Jupyter Notebooks` + вспомогательные справочные материалы. @@ -61,7 +66,7 @@ * `START_HERE.md` или аналогичный стартовый документ с маршрутом прохождения курса; * инструкция по prerequisites: `Docker`, `Docker Compose`, свободные порты, базовые команды; * пошаговый гайд по запуску стенда: `build`, `up`, проверка сервисов, открытие UI; -* краткое объяснение, как запускать Jupyter-ноутбуки в браузерном VS Code, где лежат ноутбуки и как читать структуру урока; +* краткое объяснение, как запускать ноутбуки в JupyterLab, где лежат ноутбуки и как читать структуру урока; * troubleshooting по типовым проблемам старта; * [памятка учащегося](./study_workflow.md): продолжение занятия, сохранение данных, перезапуск ядра и диагностика; @@ -71,7 +76,7 @@ * студент понимает, что нужно установить и проверить до начала курса; * студент может поднять стенд без ментора; -* студент знает, как попасть в браузерный VS Code, `MinIO`, `Trino UI`; +* студент знает, как попасть в JupyterLab, `MinIO`, `Trino UI`; * студент понимает, как устроен формат уроков и что от него ожидается. ### 3.2. Практическое ядро курса diff --git a/docs/mentor_notes.md b/docs/mentor_notes.md index 8df920c..017837d 100644 --- a/docs/mentor_notes.md +++ b/docs/mentor_notes.md @@ -36,7 +36,7 @@ - **Docker не хватает ресурсов.** Сверься с [системными требованиями](../START_HERE.md#системные-требования). Проверь отдельно память компьютера и лимит памяти Docker Desktop/WSL2: контейнерам может быть доступна лишь часть RAM хоста. - **После паузы виден старый вывод, но переменные пропали.** Разбери разницу между файлом ноутбука и ядром Python по [памятке учащегося](./study_workflow.md). Передай студенту ее до второго занятия; для обращения за помощью там есть список нужных сведений. -- **Порты заняты.** Проверь 8080, 8889, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps -a` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`. +- **Порты заняты.** Проверь 8080, 8888, 9000 и остальные [порты стенда](../START_HERE.md#порты-стенда). `docker compose ps -a` покажет, какой сервис не стартовал. Решение: остановить конфликтующий процесс или (крайний вариант) поменять порт в `docker-compose.yml`. - **Студент не читает `START_HERE.md`.** Начинает с ноутбуков до поднятия стенда. Направь обратно к стартовому документу. ### Модуль 2. Ментальная модель diff --git a/docs/stack_reference.md b/docs/stack_reference.md index b845256..015c48f 100644 --- a/docs/stack_reference.md +++ b/docs/stack_reference.md @@ -15,8 +15,8 @@ | MinIO API | `minio` | `9000` | S3-compatible endpoint | | MinIO Console | `minio` | `9001` | веб-консоль бакетов и объектов | | PostgreSQL | `postgres-iceberg` | `5432` | JDBC-каталог Iceberg | -| VS Code в браузере (code-server) | `ide` | `8889` | основной интерфейс для ноутбуков и терминала | -| JupyterLab | `jupyter` | `8888` | запасной интерфейс для тех же ноутбуков | +| JupyterLab | `jupyter` | `8888` | основной интерфейс для ноутбуков и терминала | +| VS Code в браузере (code-server) | `ide` | `8889` | альтернативный интерфейс для тех же ноутбуков | ## Основные команды @@ -33,6 +33,9 @@ docker compose up -d docker compose ps -a ``` +JupyterLab и VS Code собираются и запускаются вместе; выбирать интерфейс +можно после старта стенда. + ### Логи ```bash @@ -58,7 +61,7 @@ docker compose logs -f ide Актуальный бюджет для учащегося приведен в [системных требованиях](../START_HERE.md#системные-требования). -Он учитывает одновременную работу двух Spark worker-ов, драйвера в IDE, Trino, +Он учитывает одновременную работу двух Spark worker-ов, драйвера в Jupyter, Trino, MinIO и PostgreSQL. У каждого worker-а в Compose указаны 2 CPU и 2 ГБ для приложений Spark; это не предел потребления всей JVM или контейнера. Потребление при простое не показывает пик во время урока. @@ -110,7 +113,7 @@ Jupyter: складывать эти три числа для оценки ме Пример запуска smoke-скрипта: ```bash -docker compose exec ide python3 /opt/src/spark/cluster_smoke.py +docker compose exec jupyter python3 /opt/src/spark/cluster_smoke.py ``` ### Trino @@ -197,8 +200,35 @@ psql -h localhost -p 5432 -U iceberg -d iceberg docker compose run --rm iceberg-catalog-init ``` +### JupyterLab + +Основной интерфейс курса: `http://localhost:8888`. Открой ноутбук из списка +файлов слева; ядро **Python 3 (ipykernel)** выполняется внутри `jupyter`. +Локальный Python или venv не нужен. + +- Порт опубликован только на `127.0.0.1` хоста. +- Аутентификация и XSRF-проверка отключены для локального однопользовательского стенда. +- `./notebooks` смонтирован как `/opt/work` для чтения и записи. +- `./src` и `./data` доступны только для чтения как `/opt/src` и `/opt/data`. +- `PYTHONPATH=/opt/src`. + +Для готового стенда на удалённой машине открой туннель в терминале своего компьютера: + +```bash +ssh -N -L 8888:127.0.0.1:8888 user@host +``` + +Подставь свой SSH-адрес вместо `user@host`, оставь терминал открытым и перейди +на `http://localhost:8888`. Первый ноутбук: +`notebooks/01_environment_and_smoke_test.ipynb`. Перед Модулем 3 скачанный +на хост data bundle должен лежать в `./data/nyc_taxi`; в контейнере он доступен +как `/opt/data/nyc_taxi`. + ### VS Code в браузере +Это альтернативный интерфейс, который запускается вместе с JupyterLab. +Используй его по желанию; основной маршрут курса описан для JupyterLab. + Открой `http://localhost:8889`. Сервис `ide` запускает code-server с установленными расширениями Python и Jupyter. Python, ipykernel, Java, PySpark и зависимости курса уже находятся в образе. Локальный Python или venv не нужен. @@ -207,10 +237,23 @@ docker compose run --rm iceberg-catalog-init смонтирован в `/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 вводить не требуется. +Если сверху виден **Restricted Mode**, нажми **Manage → Trust** и закрой окно +Workspace Trust. Подтверди доверие только к своей копии учебного репозитория. +В папке **Ноутбуки** открой `01_environment_and_smoke_test.ipynb`, нажми +**Select Kernel → Python Environments** и выбери `/usr/bin/python3`. Это Python +внутри контейнера IDE. Расширение Jupyter запускает ядро там же; адрес отдельного +Jupyter Server вводить не требуется. Запускай ячейки через `Shift+Enter`, сохраняй +через **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`). Терминал IDE тоже работает +внутри контейнера; команды `docker compose` выполняй на хосте стенда. + +Совместимость зависит от браузера, его расширений и средств защиты на компьютере. +При проверке с Windows, Edge и Kaspersky сам редактор открывался, а ноутбук +блокировался дополнительной политикой безопасности страницы. Похожий случай +описан в [обсуждении code-server](https://github.com/coder/code-server/discussions/7457). +Если видишь `Error loading webview` или `Could not register service worker` +даже на `localhost`, продолжи в JupyterLab. Настраивать или отключать защиту +ради прохождения курса не требуется. Открытие окна VS Code само по себе +не подтверждает работу ноутбуков: проверь запуск ячейки и её вывод. Порт IDE опубликован только на `127.0.0.1`, без пароля, для одного пользователя. Открывай именно `localhost` или `127.0.0.1`: браузер считает их доверенным @@ -235,24 +278,9 @@ ssh -N -L 8889:127.0.0.1:8889 user@host Автоматическое обновление расширений отключено, чтобы повторный запуск использовал проверенные версии. -### JupyterLab - -- адрес: `http://localhost:8888` -- порт опубликован только на `127.0.0.1` хоста; -- аутентификация и XSRF-проверка отключены для локального одно-пользовательского стенда; -- через VS Code Remote-SSH используй `Existing Jupyter Server` с адресом `http://127.0.0.1:8888/` без token; -- `./notebooks` смонтирован как `/opt/work` -- `./src` смонтирован read-only как `/opt/src` -- `./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`. +Файлы ноутбуков общие с JupyterLab, а ядра и переменные Python отдельные. +Перед сменой интерфейса сохрани ноутбук, выполни `spark.stop()` и останови ядро. +Не редактируй один файл в двух интерфейсах одновременно. ## Как связаны Spark, Trino, PostgreSQL и MinIO @@ -280,7 +308,13 @@ JupyterLab остаётся запасным интерфейсом. Он ред ## Smoke-тесты -### Браузерная IDE и Jupyter-ноутбук +### JupyterLab и первый ноутбук + +Пройди [первый запуск ноутбука](../START_HERE.md#как-работать-с-ноутбуками): +открой Модуль 1, выбери **Python 3 (ipykernel)**, выполни ячейки и сверь вывод +Spark. После сохранения и повторного открытия вывод должен остаться в файле. + +### Дополнительная IDE и Jupyter-ноутбук На Linux с Docker Engine, после запуска стенда: @@ -302,7 +336,7 @@ bash tests/browser_ide.sh ### 1. Проверка, что Spark-кластер жив ```bash -docker compose exec ide python3 /opt/src/spark/cluster_smoke.py +docker compose exec jupyter python3 /opt/src/spark/cluster_smoke.py ``` ### 2. Проверка Spark -> Trino через общий каталог diff --git a/docs/study_workflow.md b/docs/study_workflow.md index 273b8d1..ab9cb1d 100644 --- a/docs/study_workflow.md +++ b/docs/study_workflow.md @@ -17,8 +17,8 @@ Дождись `healthy` у `ide`, `trino` и `postgres-iceberg`. У двух init-контейнеров нормальное состояние — `Exited (0)`. Повторять сборку перед каждым занятием не нужно; она понадобится после изменения образов или зависимостей. -3. Открой [VS Code в браузере](http://localhost:8889) и нужный ноутбук. - При запросе ядра выбери **Select Kernel → Python Environments → /usr/bin/python3**. +3. Открой [JupyterLab](http://localhost:8888) и нужный ноутбук в списке файлов слева. + При запросе ядра выбери **Python 3 (ipykernel)**. 4. После остановки стенда переменные Python нужно создать заново: выполни импорты, создание Spark-сессии и подключений в начале текущего ноутбука. Сохраненный вывод ячеек может быть виден еще до их запуска. @@ -30,6 +30,11 @@ Docker volumes подключаются. После переименования папки или запуска с другим `-p` можно получить новый пустой набор данных вместо предыдущего. +Вместе с JupyterLab доступен [VS Code в браузере](./stack_reference.md#vs-code-в-браузере). +Там же описаны выбор ядра и ограничения совместимости. Перед сменой интерфейса +сохрани файл, выполни `spark.stop()` и останови ядро. Файлы общие, переменные +Python — нет; не редактируй один ноутбук в двух интерфейсах одновременно. + ## Как проходить ноутбук Ноутбук состоит из пояснений и кодовых ячеек. Ядро Python выполняет код и хранит @@ -38,11 +43,11 @@ Docker volumes подключаются. После переименования - Прочитай пояснение, запусти ячейку через `Shift+Enter`, дождись окончания и сравни результат с описанием. Следующая ячейка может использовать предыдущие переменные, поэтому порядок важен. -- В самостоятельном задании заполни `TODO` и проверь результат. **Run All** +- В самостоятельном задании заполни `TODO` и проверь результат. **Run → Run All Cells** запускает код, но не выполняет задание за тебя. - Checkpoint — вопросы и проверки в конце урока. Покажи результат в своем стенде и объясни его своими словами перед переходом к следующему модулю. -- Сохраняй изменения через **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`). +- Сохраняй изменения через **File → Save Notebook** (`Ctrl+S`; на macOS — `Cmd+S`). Файл ноутбука вместе с ответами и выводом записывается в `notebooks/` на хосте. - Перед следующим модулем выполни завершающую ячейку `spark.stop()`, если она есть; иначе вызови `spark.stop()` после окончания вычислений. Это освобождает @@ -51,12 +56,13 @@ Docker volumes подключаются. После переименования Держи одну активную Spark-сессию: если несколько ноутбуков одновременно занимают все ядра worker-ов, новое задание может ждать ресурсы. Для своих SQL/Python-опытов -можно создать дополнительный ноутбук в папке **Ноутбуки**. `src/`, документация -и конфиги в IDE доступны только для чтения; их меняют в копии репозитория на хосте. +можно создать дополнительный ноутбук через **File → New → Notebook**. Он появится +в `notebooks/` на хосте. Примеры `src/` доступны Python по пути `/opt/src` только +для чтения; документацию и конфиги открывай в копии репозитория на хосте. ### Если нужно перезапустить ядро -Сначала сохрани ноутбук. В верхней панели нажми **Restart** и подтверди перезапуск. +Сначала сохрани ноутбук. Выбери **Kernel → Restart Kernel…** и подтверди перезапуск. Затем заново выполни импорты и создание Spark-сессии. Переменные Python исчезнут; файлы и записанные учебные таблицы сохранятся. @@ -86,12 +92,13 @@ Docker volume — хранилище вне файловой системы ко | Что | Где находится | После `stop` или `down` без `-v` | | --- | --- | --- | -| Код, ответы и сохраненный вывод ноутбуков | `notebooks/` на хосте; `/opt/work` и `/opt/course/notebooks` в IDE | Сохраняются | +| Код, ответы и сохраненный вывод ноутбуков | `notebooks/` на хосте; `/opt/work` в JupyterLab | Сохраняются | | Скачанные Parquet и CSV | `data/nyc_taxi/` на хосте; `/opt/data/nyc_taxi` в контейнере | Сохраняются | | Raw-файлы, данные и metadata-файлы Iceberg | Бакет `lakehouse`, volume `minio-data` | Сохраняются | | Записи каталога Iceberg | PostgreSQL, volume `postgres-data` | Сохраняются | | Переменные Python и живая Spark-сессия | Память процессов | Теряются; создай заново | -| Настройки IDE, доверие рабочей области | Файловая система контейнера `ide` | При `stop` сохраняются; при удалении или пересоздании контейнера могут сброситься | +| Настройки интерфейса JupyterLab | Файловая система контейнера `jupyter` | При `stop` сохраняются; при удалении или пересоздании контейнера могут сброситься | +| Настройки VS Code, доверие рабочей области | Файловая система контейнера `ide` | При `stop` сохраняются; при удалении или пересоздании контейнера могут сброситься | `docker compose down` удаляет контейнеры и сеть проекта. Именованные volumes остаются, поэтому после `up -d` таблицы доступны снова. Для обычного окончания @@ -128,13 +135,13 @@ docker compose up -d | Образ или зависимость не скачивается | Найди адрес источника и сервис в ошибке | Пройди [диагностику сети](./network_access.md) | | `port is already allocated` / `address already in use` | Какой порт занят, не запущена ли другая копия стенда? | Освободи нужный порт; [список портов](../START_HERE.md#порты-стенда) | | Сервис завершился, `unhealthy` или долго `starting` | `docker compose ps -a`, затем `docker compose logs --tail=100 ` | Для `postgres-iceberg` используй сервис `postgres`; проверь первую ошибку в логах | -| VS Code не открывается | `docker compose ps -a ide`, логи `ide` | Дождись `healthy`, открой `http://localhost:8889`; для сервера используй [SSH-туннель](./stack_reference.md#vs-code-в-браузере) | -| Ошибка notebook webview / service worker | Адрес в браузере и отдельная вкладка | Открой `http://localhost:8889`, без IP удаленного сервера и без встраивания в другой сайт | -| Не выбирается ядро, нет `pyspark` | Рабочая область доверенная? Выбран `/usr/bin/python3`? | Повтори [выбор ядра](../START_HERE.md#как-работать-с-ноутбуками); детали в **View → Output → Jupyter** | +| JupyterLab не открывается | `docker compose ps -a jupyter`, логи `jupyter` | Открой `http://localhost:8888`; для сервера используй [SSH-туннель](./stack_reference.md#jupyterlab) | +| VS Code не открывает ноутбук или сообщает об ошибке webview / service worker | Адрес `http://localhost:8889`, отдельная вкладка | Проверь [ограничения совместимости](./stack_reference.md#vs-code-в-браузере); продолжи в JupyterLab | +| Не выбирается ядро, нет `pyspark` | Выбрано **Python 3 (ipykernel)** в JupyterLab стенда? | Повтори [выбор ядра](../START_HERE.md#как-работать-с-ноутбуками); проверь логи `jupyter` | | `NameError`, потерялась переменная | Ядро перезапускалось или выбран другой ноутбук? | Выполни импорты и подготовительные ячейки по порядку | | Spark долго ждет, `Initial job has not accepted any resources` | В Spark UI два worker-а `ALIVE`? Есть другие приложения в `Running Applications`? | Заверши свою предыдущую сессию через `spark.stop()`; проверь логи worker-ов | | Ядро умерло, контейнер убит, подозрение на память | `docker stats --no-stream`, лимит памяти Docker/WSL2 | Сверь [системные требования](../START_HERE.md#системные-требования), закрой другие вычисления; одного кода 137 недостаточно для вывода об OOM | -| Ноутбук не сохраняется (`Permission denied`) | Это файл в папке **Ноутбуки**? Совпадает UID? | Проверь `.env` и [настройку прав перед сборкой](../START_HERE.md#быстрый-запуск); после изменения UID/GID повтори `docker compose build`, затем `docker compose up -d` | +| Ноутбук не сохраняется (`Permission denied`) | Это файл из `notebooks/`? Совпадает UID? | Проверь `.env` и [настройку прав перед сборкой](../START_HERE.md#быстрый-запуск); после изменения UID/GID повтори `docker compose build`, затем `docker compose up -d` | | Нет файлов Taxi или таблицы из прошлого модуля | Файлы в `data/nyc_taxi`, предыдущие модули, прежняя папка проекта | Для raw нужен Модуль 3, для bronze — 4, для silver — 5; после сброса восстанови их по порядку | ### Что передать ментору @@ -145,9 +152,9 @@ docker compose up -d ```bash docker compose version docker compose ps -a -docker compose logs --tail=100 ide +docker compose logs --tail=100 jupyter ``` -В последней команде замени `ide` на проблемный сервис, если ошибка в другом компоненте. -Для ошибки ноутбука добавь выбранный путь Python и вывод ячейки. Пароли, токены +В последней команде замени `jupyter` на проблемный сервис, если ошибка в другом компоненте. +Для ошибки ноутбука добавь имя выбранного ядра и вывод ячейки. Пароли, токены и адреса прокси с учетными данными в сообщение не включай. diff --git a/notebooks/01_environment_and_smoke_test.ipynb b/notebooks/01_environment_and_smoke_test.ipynb index 8880453..a702b0e 100644 --- a/notebooks/01_environment_and_smoke_test.ipynb +++ b/notebooks/01_environment_and_smoke_test.ipynb @@ -28,13 +28,13 @@ "Если стенд еще не готов, выполни подготовку и запуск по [START_HERE](../START_HERE.md#быстрый-запуск).\n", "Если возвращаешься после паузы, используй [памятку учащегося](../docs/study_workflow.md).\n", "\n", - "Важно: `docker compose build`, `docker compose up -d`, `docker compose ps -a` и просмотр логов выполняются в терминале хоста; терминал браузерного VS Code работает внутри контейнера.\n", + "Важно: `docker compose build`, `docker compose up -d`, `docker compose ps -a` и просмотр логов выполняются в терминале хоста; терминал JupyterLab работает внутри контейнера.\n", "\n", "Ожидаемое состояние перед началом:\n", "\n", "- контейнеры `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`, `trino`, `jupyter`, `ide` уже подняты;\n", - "- открываются `Spark UI`, `Trino UI`, `MinIO Console` и браузерный VS Code;\n", - "- ты выбрал ядро Python `/usr/bin/python3` внутри контейнера `ide` (Select Kernel → Python Environments).\n" + "- открываются `Spark UI`, `Trino UI`, `MinIO Console` и JupyterLab;\n", + "- в JupyterLab выбрано ядро `Python 3 (ipykernel)` внутри контейнера `jupyter` (Kernel → Change Kernel…).\n" ] }, { @@ -50,7 +50,7 @@ "| `PostgreSQL` | `catalog`: хранит метаданные JDBC-каталога Iceberg |\n", "| `Spark` | `compute`: выполняет PySpark и Spark SQL |\n", "| `Trino` | `compute`: читает те же таблицы через общий каталог |\n", - "| `VS Code / JupyterLab` | Точка входа в учебные ноутбуки |\n", + "| `JupyterLab` | Точка входа в учебные ноутбуки |\n", "\n", "В этом модуле мы не строим пайплайн и не создаём Iceberg-таблицы. Задача только одна: убедиться, что среда рабочая и понятная.\n" ] @@ -147,7 +147,7 @@ "\n", "Сделай руками и проверь себя:\n", "\n", - "1. Открой `Spark UI`, `Trino UI`, `MinIO Console` и браузерный VS Code.\n", + "1. Открой `Spark UI`, `Trino UI`, `MinIO Console` и JupyterLab.\n", "2. Сопоставь каждый сервис с одной из ролей: `storage`, `catalog`, `compute`, `entrypoint`.\n", "3. Объясни, почему этот smoke test не должен работать в `local[*]` режиме.\n", "4. На хосте выполни `docker compose ps -a` и посмотри, какие контейнеры должны быть в состоянии `Up`.\n", @@ -182,7 +182,7 @@ "К концу модуля ты должен уметь подтвердить:\n", "\n", "- стенд поднят и основные контейнеры живы;\n", - "- `Spark UI`, `MinIO Console`, `Trino UI` и браузерный VS Code открываются;\n", + "- `Spark UI`, `MinIO Console`, `Trino UI` и JupyterLab открываются;\n", "- smoke test напечатал `Spark cluster smoke test passed.` и `result_sum=499999500000`;\n", "- ты понимаешь назначение `MinIO`, `PostgreSQL`, `Spark`, `Trino` и IDE;\n", "- ты знаешь, что первый маршрут диагностики начинается с `docker compose ps -a`, `docker compose logs -f ` и проверки UI.\n",