# START HERE

Здесь ты подготовишь окружение и выполнишь первое вычисление в Spark.
К концу запуска в ноутбуке появится `Spark cluster smoke test passed.`, а результат
сохранится в файле на твоем компьютере. Smoke test — короткая проверка, что
основные компоненты работают вместе.

Если стенд уже собран, открой [памятку для следующего занятия](./docs/study_workflow.md).
Она объясняет, как продолжить работу, что сохраняется и куда смотреть при ошибках.

## Маршрут прохождения

1. Подготовь Docker, ресурсы и локальную копию репозитория.
2. Скачай образы, собери окружение и проверь запуск сервисов.
3. Открой первый ноутбук в браузерном VS Code и проверь результат вычисления.
4. Продолжи по [программе курса](./docs/course_program.md#маршрут-по-модулям).

Датасет Taxi понадобится перед Модулем 3, DBeaver необязателен и понадобится
только перед Модулем 6. Для первого ноутбука их готовить не нужно.

<a id="prerequisites"></a>

## Что подготовить

- Docker с запущенным движком и Docker Compose 2.17+ с BuildKit.
- Современный браузер; основной интерфейс курса — VS Code на `localhost:8889`.
- Git для скачивания репозитория или его распакованную ZIP-копию.
- Свободные порты из таблицы ниже и доступ к источникам образов и зависимостей.

Команды ниже рассчитаны на Bash: терминал Linux/macOS или терминал Linux
в WSL2 на Windows с включенной интеграцией Docker Desktop. Выполняй их на
машине, где работает Docker. Терминал внутри браузерного VS Code для запуска
`docker compose` не подходит.

### Системные требования

Ориентир для одного учащегося и основного набора Taxi за три месяца:

| Ресурс | Рекомендация | Что проверить |
| --- | --- | --- |
| Процессор | Не менее 4 CPU, доступных Docker | В Docker Desktop/WSL2 может стоять меньший лимит |
| Память Docker | Ориентир — 8 ГБ RAM; 10 ГБ дают дополнительный запас | Это память для среды Docker, а не общий объем памяти компьютера |
| Память компьютера | 16 ГБ RAM или больше | Оставь память ОС, браузеру и другим приложениям |
| Свободное место | Не менее 20 ГБ перед первой сборкой; 30 ГБ с запасом | На диске Docker и в папке репозитория: образы, кэш сборки, исходные данные и таблицы |

Это рекомендуемый бюджет для одного активного ноутбука, а не измеренный минимум.
На Windows с WSL2 по умолчанию доступно 50% RAM компьютера: при 16 ГБ это 8 ГБ
для всей WSL2, включая Docker. Лимит можно настроить, это не аппаратное
ограничение. См. [настройки WSL2](https://learn.microsoft.com/en-us/windows/wsl/wsl-config#main-wsl-settings)
и [ресурсы Docker Desktop](https://docs.docker.com/desktop/settings-and-maintenance/settings/#resources).

Trino ограничен 2 ГиБ памяти контейнера и 1 ГиБ Java heap. Проверка запросов
на данных курса описана в [справочнике](./docs/stack_reference.md#ресурсы-и-проверенная-среда).
Полный курс под общим жестким лимитом Docker 8 ГБ пока не проверен. В WSL2 часть
памяти также нужна самой Linux-среде; закрой другие тяжелые задачи на время урока.
Место внутри диска Docker и свободное место на диске компьютера — отдельные ограничения.

С добавлением VS Code образ окружения вырос примерно на 1,2 ГБ относительно
Jupyter; базовые слои у них общие. MinIO скачивается готовым, компилировать его
не нужно. [Основания оценок и границы проверки](./docs/stack_reference.md#ресурсы-и-проверенная-среда).

Python, Java, Jupyter и расширения VS Code устанавливаются при сборке образов.
На компьютере не нужно создавать venv или устанавливать Python-пакеты.

Для первой сборки нужен интернет. Если ты работаешь из РФ или сети с
ограничениями, при ошибке скачивания используй
[инструкцию по доступу к репозиториям](./docs/network_access.md). Она различает
проблемы скачивания образов и зависимостей внутри сборки.

### Проверка до сборки

Открой терминал в папке репозитория — там, где лежит `docker-compose.yml`:

```bash
docker version
docker compose version
docker info --format 'CPUs={{.NCPU}} MemoryBytes={{.MemTotal}}'
docker compose config --quiet
```

В `docker version` должны быть разделы Client и Server, версия Compose — не
ниже 2.17. `docker info` показывает ресурсы, которые видит Docker; память дана
в байтах (8 ГиБ — 8 589 934 592 байта). Последняя команда при успехе
ничего не печатает. Если Docker не отвечает или конфигурация не читается,
исправь эту ошибку до сборки.

## Порты стенда

| Сервис | Адрес | Зачем нужен |
| --- | --- | --- |
| Spark Master UI | `http://localhost:8080` | Проверка мастера Spark и подключённых worker-ов |
| Spark Worker 1 UI | `http://localhost:8081` | Проверка первого worker-а |
| Spark Worker 2 UI | `http://localhost:8082` | Проверка второго worker-а |
| 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` | Запасной интерфейс для ноутбуков |
| PostgreSQL | `localhost:5432` | JDBC-каталог Iceberg, нужен для диагностики |

## Быстрый запуск

Все команды выполняются из корня репозитория.

На Linux и в WSL2 проверь владельца файлов:

```bash
id -u
id -g
```

Это UID и GID — числовые идентификаторы пользователя и группы. В контейнере по
умолчанию используются `1000` и `100`. Если значения отличаются, до сборки
создай `.env` в корне репозитория и укажи `NB_UID` и `NB_GID` со своими числами.
Например, для вывода `1001` и `1001`:

```dotenv
NB_UID=1001
NB_GID=1001
```

Если `.env` уже есть, измени только эти строки, сохранив остальные настройки.
Файл остается между занятиями. Образец — [`.env.example`](./.env.example).
На macOS с Docker Desktop обычно подходят значения по умолчанию.

### 1. Скачать готовые образы и собрать окружение

```bash
docker compose pull minio minio-init postgres trino
docker compose build
```

Первая команда проверяет загрузку готовых сервисов до сборки окружения.
MinIO уже собран; для Spark, Jupyter и IDE первая сборка скачивает зависимости
и зависит по времени от сети и компьютера. Дождись завершения без ошибок;
не переходи к запуску после неудачной сборки. Повторная сборка использует кэш Docker.

### 2. Поднять стенд

```bash
docker compose up -d
```

### 3. Проверить статус контейнеров

```bash
docker compose ps -a
```

Ожидаемое состояние:

- `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`,
  `trino`, `jupyter`, `ide` работают (`Up`); у `postgres-iceberg`, `trino` и `ide`
  дождись `healthy`;
- `minio-init` и `iceberg-catalog-init` заканчивают работу со статусом `Exited (0)`.
  Это успешная разовая подготовка хранилища и каталога. `Exited (1)` и другой
  ненулевой код требуют проверки логов.

Флаг `-a` показывает и завершившиеся контейнеры. Сам по себе статус `Up` еще
не доказывает, что вычисления работают: дальше проверим их в ноутбуке.

## Куда заходить после старта

| Что открыть | Что должно быть видно |
| --- | --- |
| [Spark Master](http://localhost:8080) | Два worker-а в состоянии `ALIVE` |
| [MinIO Console](http://localhost:9001) | После входа `minioadmin` / `minioadmin` виден бакет `lakehouse` — контейнер для файлов курса |
| [VS Code](http://localhost:8889) | Слева папки **Ноутбуки**, **Примеры (только чтение)**, **Документация (только чтение)** |

В [Trino UI](http://localhost:8090) для входа достаточно имени, например `student`;
пароль в стенде не задан. Сейчас достаточно проверить, что интерфейс открывается.
Чтение общих таблиц через Trino разберем в Модуле 6.

Этот маршрут предполагает Docker на твоем компьютере: `localhost` относится
к машине с браузером. Доступ к VS Code на удаленном сервере описан отдельно
в [инструкции по SSH-туннелю](./docs/stack_reference.md#vs-code-в-браузере).

## Роли сервисов в стенде

| Сервис | Роль в модуле |
| --- | --- |
| `MinIO` | `storage`: объектное хранилище для данных и файлов Iceberg |
| `PostgreSQL` | `catalog`: хранит метаданные JDBC-каталога Iceberg |
| `Spark` | `compute`: выполняет PySpark и Spark SQL задания |
| `Trino` | `compute`: читает те же таблицы через общий каталог |
| `VS Code / 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`, затем остальные
   ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через
   **File → Save** (`Ctrl+S`; на macOS — `Cmd+S`).

Терминал VS Code тоже работает внутри контейнера. Команды `docker compose`
выполняй в терминале хоста, откуда запускал стенд.

### Как понять, что первый запуск прошел

В третьей кодовой ячейке первого ноутбука появится отчет, содержащий:

```text
Spark cluster smoke test passed.
master_url=spark://spark-master:7077
result_sum=499999500000
expected_sum=499999500000
```

В отчете есть и другие строки; значения выше должны совпасть. Затем выполни
самостоятельное задание: замени `TODO` в словаре `service_roles` ролями сервисов.
Сам факт запуска ячейки с `TODO` не означает, что задание выполнено.

В конце выполни ячейку `spark.stop()`, сохрани ноутбук и проверь, что его изменения
видны в `notebooks/01_environment_and_smoke_test.ipynb` на хосте. После повторного
открытия сохраненный вывод остается виден. Такой вывод — запись прошлого запуска;
он не означает, что ядро Python и Spark-сессия продолжают работать.

Правила запуска ячеек, перехода между модулями и сохранения данных собраны в
[памятке учащегося](./docs/study_workflow.md).

Запасной интерфейс — JupyterLab на `http://localhost:8888`. Файлы ноутбуков общие,
а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и заверши
Spark-сессию через `spark.stop()`; не редактируй один файл в двух интерфейсах
одновременно.

## Базовая диагностика

Начни с `docker compose ps -a` и логов проблемного сервиса, например:

```bash
docker compose logs --tail=100 ide
```

Выбери свой симптом в [таблице диагностики](./docs/study_workflow.md#если-что-то-не-работает).
При ошибке скачивания сразу открой [диагностику сети](./docs/network_access.md).

## Restart и reset

Для обычной паузы используй `docker compose stop`, на следующем занятии —
`docker compose up -d`. Порядок действий и последствия удаления контейнеров
описаны в [памятке](./docs/study_workflow.md#закончить-занятие).

Полный сброс удаляет учебные таблицы и каталог. Его команда вынесена в
[отдельный раздел](./docs/study_workflow.md#начать-с-чистых-данных), чтобы не путать
с окончанием занятия.

## Подготовка учебного датасета (перед Модулем 3)

Перед `notebooks/03_raw_ingest_and_first_read.ipynb` нужно заранее скачать учебный data bundle на хост, а не изнутри ноутбука.

Скачай каноническое учебное подмножество `NYC TLC Yellow Taxi Trip Records`:

```bash
mkdir -p data/nyc_taxi
curl -fLo data/nyc_taxi/yellow_tripdata_2024-01.parquet \
  https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet
curl -fLo data/nyc_taxi/yellow_tripdata_2024-02.parquet \
  https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-02.parquet
curl -fLo data/nyc_taxi/yellow_tripdata_2024-03.parquet \
  https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-03.parquet
curl -fLo data/nyc_taxi/taxi_zone_lookup.csv \
  https://d37ci6vzurychx.cloudfront.net/misc/taxi_zone_lookup.csv
```

Проверь, что файлы на месте:

```bash
ls -lh data/nyc_taxi/
```

Минимальный набор для курса:

- `yellow_tripdata_2024-01.parquet`
- `yellow_tripdata_2024-02.parquet`
- `yellow_tripdata_2024-03.parquet`
- `taxi_zone_lookup.csv`

Если хочешь расширенный режим, можешь скачать все 12 месяцев `2024`, но основной маршрут курса и примеры опираются на первые 3 месяца.

## Подключение DBeaver к Trino (перед Модулем 6)

- Зачем: в Модуле 6 можно работать с Trino через DBeaver параллельно с ноутбуком — привычный SQL-интерфейс.
- Предусловие: DBeaver установлен (ссылка на [dbeaver.io/download](https://dbeaver.io/download/)). Необязателен — ноутбук работает без DBeaver.
- Шаги: New Database Connection -> Trino. Host: `localhost`. Port: `8090`. Database/Catalog: `lakehouse`. Username: любая строка (напр. `student`). Password: пусто. Test Connection -> Finish.
- Проверка: `SHOW SCHEMAS FROM lakehouse;`. После модулей 4–5 должны быть видны `bronze` и `silver`; до их прохождения этих схем может еще не быть.
- Troubleshooting: стенд поднят? контейнер `trino` Up? порт 8090 свободен?

## Что делать дальше

После первого ноутбука открой [маршрут по модулям](./docs/course_program.md#маршрут-по-модулям).
В нем есть ссылки на все восемь уроков и результат, который нужно получить
перед переходом дальше. Для следующего занятия сохрани ссылку на
[памятку учащегося](./docs/study_workflow.md).