# START HERE

Этот документ нужен для первого входа в курс: поднять стенд, проверить сервисы, открыть интерфейсы, выполнить базовый smoke test и подготовить локальный data bundle для следующих модулей.

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

1. Проверить prerequisites.
2. Собрать и поднять стенд.
3. Убедиться, что контейнеры живы.
4. Открыть основные UI.
5. Открыть VS Code в браузере и выполнить `notebooks/01_environment_and_smoke_test.ipynb`.
6. Перед Модулем 3 подготовить учебный датасет в `./data/nyc_taxi`.
7. При проблемах использовать логи и шаги диагностики из этого документа.

## Prerequisites

Нужно заранее установить:

- Docker;
- Docker Compose 2.17+ с BuildKit (`docker compose version`);
- современный браузер для UI;
- свободные порты на хосте.

Рекомендуемые ресурсы хоста:

- не менее `4 vCPU`;
- не менее `10 GB RAM`, иначе `Spark`, `Trino` и IDE могут стартовать нестабильно;
- хотя бы `20 GB` свободного места под образы, кэш первой сборки и контейнеры.

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

Для первой сборки нужен доступ к внешним репозиториям. Если ты работаешь из РФ
или сети с ограничениями, при ошибке скачивания используй
[инструкцию по доступу к репозиториям](./docs/network_access.md): в ней есть
резервный источник MinIO и отдельные шаги для 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 пользователь контейнера должен иметь доступ к файлам ноутбуков. Если
твой UID отличается от `1000`, перед сборкой задай его в текущем терминале:

```bash
export NB_UID=$(id -u) NB_GID=$(id -g)
```

Для Docker Desktop на macOS и Windows обычно подходят значения по умолчанию.

### 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
```

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

- контейнеры `spark-master`, `spark-worker-1`, `spark-worker-2`, `minio`, `postgres-iceberg`, `trino`, `jupyter`, `ide` находятся в состоянии `Up`, у `ide` появляется статус `healthy`;
- однократные init-контейнеры вроде `minio-init` и `iceberg-catalog-init` могут завершиться после успешной инициализации.

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

Открой в браузере:

- `http://localhost:8080` для `Spark Master UI`;
- `http://localhost:8090` для `Trino UI`;
- `http://localhost:9001` для `MinIO Console`;
- `http://localhost:8889` для `VS Code в браузере`.

Для входа в `MinIO Console` используй:

- логин: `minioadmin`;
- пароль: `minioadmin`.

Если интерфейсы открываются, переходи в VS Code и запускай:

```text
notebooks/01_environment_and_smoke_test.ipynb
```

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

| Сервис | Роль в модуле |
| --- | --- |
| `MinIO` | `storage`: объектное хранилище для данных и файлов Iceberg |
| `PostgreSQL` | `catalog`: хранит метаданные JDBC-каталога Iceberg |
| `Spark` | `compute`: выполняет PySpark и Spark SQL задания |
| `Trino` | `compute`: читает те же таблицы через общий каталог |
| `VS Code / JupyterLab` | Интерфейсы для учебных ноутбуков |

## Как работать с ноутбуками

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`, затем остальные
   ячейки по порядку. Результат появится под ячейкой. Сохрани ноутбук через `Ctrl+S`.

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

Файлы доступны в IDE так:

- `./notebooks` смонтирован в контейнер как `/opt/work`;
- `./src` смонтирован read-only как `/opt/src`;
- весь репозиторий доступен read-only в `/opt/course`; его папка `notebooks/`
  доступна для записи, поэтому правки из IDE сохраняются на хосте;
- `./data` смонтирован read-only как `/opt/data`;
- `PYTHONPATH=/opt/src`, поэтому helper-скрипты из `src/` доступны для импорта в ноутбуках;
- учебный data bundle для Модуля 3 доступен по пути `/opt/data/nyc_taxi`.

Запасной интерфейс — JupyterLab на `http://localhost:8888`. Файлы ноутбуков общие,
а ядра и переменные Python отдельные. Перед переходом сохрани ноутбук и останови
его ядро. Подключение с удалённой машины описано в
[техническом reference](./docs/stack_reference.md#vs-code-в-браузере).

Ноутбуки берут адрес кластера из
[`spark/spark-defaults.conf`](./spark/spark-defaults.conf). Если изменил его,
перезапусти ядро и заново создай Spark-сессию. Повторный запуск ячейки с
`getOrCreate()` использует текущую сессию. При перезапуске ядра переменные Python
сбрасываются, а учебные таблицы и файлы сохраняются.

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

### Посмотреть список контейнеров

```bash
docker compose ps
```

### Посмотреть логи конкретного сервиса

```bash
docker compose logs -f spark-master
docker compose logs -f trino
docker compose logs -f minio
docker compose logs -f jupyter
docker compose logs -f ide
```

### Типовые первые проверки

- Ошибка скачивания образа или зависимостей: найди имя недоступного источника
  в сообщении и открой [диагностику сети](./docs/network_access.md).
- `Spark UI` не открывается: проверь `docker compose ps` и логи `spark-master`.
- `Trino UI` не открывается: проверь `docker compose ps` и логи `trino`.
- `JupyterLab` не открывается: проверь `docker compose ps` и логи `jupyter`.
- VS Code не открывается: проверь `docker compose ps ide` и логи `ide`.
- Вместо ноутбука ошибка webview/service worker: открой `http://localhost:8889`
  в отдельной вкладке, без IP сервера и без встраивания в другой сайт.
- Ядро не выбирается: убедись, что рабочая область доверенная, и выбери
  `/usr/bin/python3` в **Python Environments**. Для подробностей открой
  **View → Output → Jupyter**.
- `MinIO Console` не открывается: проверь `docker compose ps` и логи `minio`.
- smoke test падает из ноутбука: сначала убедись, что `spark-master` и worker-ы видны в `Spark UI`.

## Restart и reset

### Мягкий перезапуск стенда

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

### Полный reset с удалением данных

```bash
docker compose down -v
docker compose up -d
```

Используй полный reset, если хочешь пройти практику заново с чистого состояния.

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

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

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

```bash
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;`. Ожидаем: `bronze`, `default`, `information_schema`, `silver`.
- Troubleshooting: стенд поднят? контейнер `trino` Up? порт 8090 свободен?

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

- пройти `notebooks/01_environment_and_smoke_test.ipynb`;
- пройти `notebooks/02_lakehouse_mental_model.ipynb`;
- подготовить data bundle по инструкции выше и пройти `notebooks/03_raw_ingest_and_first_read.ipynb`;
- свериться с программой курса в `docs/course_program.md`;
- после прохождения первых модулей переходить к следующим учебным материалам.