# Как заниматься со стендом

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