Учебная дата-платформа кликстрима

Этим стендом можно пользоваться самостоятельно. Он также входит в план обучения Data Engineering Roadmap как курсовая работа. Если вам нужна помощь, обратитесь к автору материалов — ментору @dementev_dev.

Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок и графиков. Это преемник учебного стенда clickstream-ch-kafka-superset-demo.

В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka, Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда приезжают из генератора и идут по слоям STG → ODS → DDS → DM. make up наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы разобраться в устройстве, начните с путеводителя, а учиться — с уроков.

Быстрый старт

Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано сейчас, в байтах, покажет docker info --format '{{.MemTotal}}'. В WSL2 это поднимается параметром memory в файле .wslconfig домашнего каталога пользователя Windows; после правки нужен wsl --shutdown. Если своей машины не хватает, стенд одинаково хорошо живёт на недорогом VPS.

make up нужны curl и jq: первым он ходит в Airflow, вторым читает паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны порты 23000, 28080, 28088, 28123, 28124, 29000, 29001, 29090 и 29092. Всем целям генератора в generator/ нужен uv.

Сначала скопируйте настройки стенда:

cp .env.example .env
make up

make up сам ждет заливки стартового мира; что он делает по шагам и какие проверки есть у стенда, описано в карте проверок.

.env.example — образец обязательной локальной настройки. В нём живут имя экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца верно не везде — DOCKER_GID: у группы docker на каждой машине свой номер, и свой подскажет getent group docker. Пока он не сойдётся, стенд работает весь, кроме дагов модельного времени. compose.yaml не дублирует их умолчаниями: если значения нет в .env, Compose сразу предложит скопировать образец. Внутренние адреса, имена топиков и версии образов описывают сам стенд, поэтому записаны литералами в compose.yaml и Dockerfile.

Учётные данные Postgres и Grafana применяются при создании их томов. После первого запуска меняйте их только вместе с make clean: команда удалит все локальные данные стенда, а следующий make up создаст их с новыми значениями.

Адреса и пароли

С настройками из .env.example порты доступны только с локальной машины:

• нода 1 — http://127.0.0.1:28123, нативный порт 29000;
• нода 2 — http://127.0.0.1:28124, нативный порт 29001;
• Kafka — 127.0.0.1:29092;
• Airflow — http://127.0.0.1:28080, пользователь admin, пароль airflow;
• Superset — http://127.0.0.1:28088, пользователь admin, пароль superset;
• Prometheus — http://127.0.0.1:29090;
• Grafana — http://127.0.0.1:23000, пользователь admin, пароль admin.

Службы, пользователи и роли, применение настроек и результаты сверки конфигурации описаны в справочнике стенда.

Сдвинуть мир вперед

В Airflow запустите даг world_next_day: по умолчанию он сыграет один день, а в форме запуска можно задать другое число дней. Снимите с паузы world_live, и мир поедет сам в темпе модельного времени. Подробности — в справочнике мира.

Вернуть мир к началу

make rebuild-storage запустит в Airflow явную пересборку: удалит прикладные базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему и данные заново. Службы и их тома останутся на месте. Перед пересборкой поставьте world_live на паузу и дайте уже начатому шаговому дагу закончить день.

Выключить или сбросить целиком

make down остановит контейнеры без удаления данных. make clean удалит весь стенд вместе с именованными томами и для обычной работы не нужен.

Подключиться из DBeaver

Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост 127.0.0.1, порт 28123, пользователя analyst и пароль из переменной CLICKHOUSE_ANALYST_PASSWORD в .env; в образце это analyst-26-reader. Ко второй ноде — порт 28124.

Пользователь analyst читает все слои и справочники. Нативные порты 29000 и 29001 нужны clickhouse-client, но не DBeaver. Остальные пользователи и роли описаны в справочнике стенда.

Документация

• docs/handbook/ — путеводитель по стенду и порядок чтения.
• docs/labs/ — учебные задания с порядком прохождения и самопроверкой.
• docs/specs/ — спеки: источник истины о задуманном.
• docs/adr/ — принятые решения с доводами и отвергнутыми вариантами: почему сделано так, а не иначе.
• docs/architecture/ — рабочие справочники по зонам ответственности:
  • хранилище — конвенции имён, раскладка по шардам, приём событий, карта таблиц.
  • конвейер — движение данных между слоями и работа дагов.
  • мир и модельное время — начальные данные, ход дней и управление генератором.
  • стенд — службы, доступ и настройка.
  • проверки — что утверждает каждая цель make и куда класть новую проверку.
  • мониторинг — сбор метрик и устройство дашборда.
  • Superset — подключения, наборы данных и граница автоматической настройки.
• docs/research/ — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события.
• docs/formats/ — описания форматов источников: по ним пишется сторона хранилища. Собираются из кода командой make docs в generator/, руками не правятся.
• AGENTS.md — контракт работы в репозитории.