docs(course): make JupyterLab the primary notebook interface

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` из ноутбуков;

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. Практическое ядро курса

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. Ментальная модель

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 через общий каталог

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 <service>` | Для `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` на проблемный сервис, если ошибка в другом компоненте.
+Для ошибки ноутбука добавь имя выбранного ядра и вывод ячейки. Пароли, токены
 и адреса прокси с учетными данными в сообщение не включай.