154 lines
14 KiB
Markdown
154 lines
14 KiB
Markdown
# Как заниматься со стендом
|
||
|
||
Для первой сборки используй [START_HERE](../START_HERE.md), для выбора урока —
|
||
[маршрут по модулям](./course_program.md#маршрут-по-модулям). Эта памятка нужна,
|
||
когда окружение уже готово.
|
||
|
||
## Начать следующее занятие
|
||
|
||
1. Запусти Docker и открой терминал хоста в той же папке репозитория.
|
||
2. Выполни:
|
||
|
||
```bash
|
||
docker compose up -d
|
||
docker compose ps -a
|
||
```
|
||
|
||
Дождись `healthy` у `ide`, `trino` и `postgres-iceberg`. У двух init-контейнеров
|
||
нормальное состояние — `Exited (0)`. Повторять сборку перед каждым занятием
|
||
не нужно; она понадобится после изменения образов или зависимостей.
|
||
3. Открой [VS Code в браузере](http://localhost:8889) и нужный ноутбук.
|
||
При запросе ядра выбери **Select Kernel → Python Environments → /usr/bin/python3**.
|
||
4. После остановки стенда переменные Python нужно создать заново: выполни
|
||
импорты, создание Spark-сессии и подключений в начале текущего ноутбука.
|
||
Сохраненный вывод ячеек может быть виден еще до их запуска.
|
||
5. Продолжи с места, на котором остановился. Перед повтором ячеек с записью
|
||
данных, `INSERT`, `CREATE OR REPLACE`, `DROP` или очисткой истории прочитай
|
||
пояснение: повторный запуск может изменить таблицу или создать новый snapshot.
|
||
|
||
Используй прежнюю папку репозитория: имя Compose-проекта определяет, какие
|
||
Docker volumes подключаются. После переименования папки или запуска с другим
|
||
`-p` можно получить новый пустой набор данных вместо предыдущего.
|
||
|
||
## Как проходить ноутбук
|
||
|
||
Ноутбук состоит из пояснений и кодовых ячеек. Ядро Python выполняет код и хранит
|
||
переменные в памяти. Spark-сессия связывает этот Python-процесс с кластером.
|
||
|
||
- Прочитай пояснение, запусти ячейку через `Shift+Enter`, дождись окончания и
|
||
сравни результат с описанием. Следующая ячейка может использовать предыдущие
|
||
переменные, поэтому порядок важен.
|
||
- В самостоятельном задании заполни `TODO` и проверь результат. **Run All**
|
||
запускает код, но не выполняет задание за тебя.
|
||
- Checkpoint — вопросы и проверки в конце урока. Покажи результат в своем
|
||
стенде и объясни его своими словами перед переходом к следующему модулю.
|
||
- Сохраняй изменения через **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`).
|
||
Файл ноутбука вместе с ответами и выводом записывается в `notebooks/` на хосте.
|
||
- Перед следующим модулем выполни завершающую ячейку `spark.stop()`, если она
|
||
есть; иначе вызови `spark.stop()` после окончания вычислений. Это освобождает
|
||
ресурсы Spark для следующего приложения. Закрытие вкладки браузера само по
|
||
себе не останавливает вычисления.
|
||
|
||
Держи одну активную Spark-сессию: если несколько ноутбуков одновременно занимают
|
||
все ядра worker-ов, новое задание может ждать ресурсы. Для своих SQL/Python-опытов
|
||
можно создать дополнительный ноутбук в папке **Ноутбуки**. `src/`, документация
|
||
и конфиги в IDE доступны только для чтения; их меняют в копии репозитория на хосте.
|
||
|
||
### Если нужно перезапустить ядро
|
||
|
||
Сначала сохрани ноутбук. В верхней панели нажми **Restart** и подтверди перезапуск.
|
||
Затем заново выполни импорты и создание Spark-сессии. Переменные Python исчезнут;
|
||
файлы и записанные учебные таблицы сохранятся.
|
||
|
||
Перезапуск нужен, например, после изменения адреса кластера в
|
||
`spark/spark-defaults.conf` или после остановки Spark-сессии, с которой хочешь
|
||
продолжить работу. Повторный `getOrCreate()` при живой сессии использует ее;
|
||
подробнее это разбирается в Модуле 3.
|
||
|
||
## Закончить занятие
|
||
|
||
Сохрани ноутбук, дождись завершения вычислений и запиши для себя номер модуля
|
||
и следующую ячейку. Затем в терминале хоста выполни:
|
||
|
||
```bash
|
||
docker compose stop
|
||
```
|
||
|
||
Контейнеры остановятся и освободят занятую ими оперативную память. Файлы
|
||
ноутбуков, исходные данные и таблицы останутся. На следующем занятии используй
|
||
`docker compose up -d` из начала этой памятки.
|
||
|
||
## Что и где сохраняется
|
||
|
||
Docker volume — хранилище вне файловой системы контейнера. В этом стенде два
|
||
таких хранилища: `minio-data` с объектами и `postgres-data` с каталогом Iceberg.
|
||
Имена volumes в Docker обычно имеют префикс Compose-проекта.
|
||
|
||
| Что | Где находится | После `stop` или `down` без `-v` |
|
||
| --- | --- | --- |
|
||
| Код, ответы и сохраненный вывод ноутбуков | `notebooks/` на хосте; `/opt/work` и `/opt/course/notebooks` в IDE | Сохраняются |
|
||
| Скачанные 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` сохраняются; при удалении или пересоздании контейнера могут сброситься |
|
||
|
||
`docker compose down` удаляет контейнеры и сеть проекта. Именованные volumes
|
||
остаются, поэтому после `up -d` таблицы доступны снова. Для обычного окончания
|
||
занятия достаточно `stop`. Поведение команд описано также в документации Docker:
|
||
[stop](https://docs.docker.com/reference/cli/docker/compose/stop/),
|
||
[down](https://docs.docker.com/reference/cli/docker/compose/down/).
|
||
|
||
### Начать с чистых данных
|
||
|
||
Этот шаг нужен только для осознанного повторного прохождения с пустым
|
||
хранилищем. Он удалит оба volumes: raw-данные в MinIO, таблицы, их историю
|
||
и записи каталога PostgreSQL. Сохраненные ноутбуки и скачанные файлы в `data/`
|
||
на хосте останутся.
|
||
|
||
```bash
|
||
docker compose down -v
|
||
docker compose up -d
|
||
```
|
||
|
||
После сброса в ноутбуках еще может быть старый вывод. Заново создай raw в
|
||
Модуле 3, bronze в Модуле 4 и silver в Модуле 5, прежде чем продолжать модули,
|
||
которые используют эти данные. Сброс не является способом исправить сеть
|
||
или выбор ядра.
|
||
|
||
## Если что-то не работает
|
||
|
||
Все `docker compose` команды ниже выполняются в терминале хоста из корня
|
||
репозитория. Имя сервиса для логов берется из колонки `SERVICE` в `ps`:
|
||
например, `postgres`, хотя контейнер называется `postgres-iceberg`.
|
||
|
||
| Симптом | Первая проверка | Что сделать дальше |
|
||
| --- | --- | --- |
|
||
| Docker не отвечает | `docker version`: есть ли раздел Server? | Запусти Docker; при `permission denied` проверь доступ своего пользователя к Docker |
|
||
| Образ или зависимость не скачивается | Найди адрес источника и сервис в ошибке | Пройди [диагностику сети](./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** |
|
||
| `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` |
|
||
| Нет файлов Taxi или таблицы из прошлого модуля | Файлы в `data/nyc_taxi`, предыдущие модули, прежняя папка проекта | Для raw нужен Модуль 3, для bronze — 4, для silver — 5; после сброса восстанови их по порядку |
|
||
|
||
### Что передать ментору
|
||
|
||
Укажи ОС, модуль, ячейку или команду, ожидаемый результат и полный текст ошибки.
|
||
Приложи вывод:
|
||
|
||
```bash
|
||
docker compose version
|
||
docker compose ps -a
|
||
docker compose logs --tail=100 ide
|
||
```
|
||
|
||
В последней команде замени `ide` на проблемный сервис, если ошибка в другом компоненте.
|
||
Для ошибки ноутбука добавь выбранный путь Python и вывод ячейки. Пароли, токены
|
||
и адреса прокси с учетными данными в сообщение не включай.
|