Build & Deploy Custom Superset Viz Plugin

Введение в Build & Deploy Custom Superset Viz Plugin

Эта статья содержит описание процесса развертывания среды разработки, создания плагина, а также его деплой через сборку нового образа Docker.

Основная проблема разработки плагина заключается в том что, чтобы построить кастомную визуализацию — необходимо знать множество технологий. Начиная с git, docker, React, Docker-compose, npm, yarn и т.д. И это не касаясь еще процесса обработки данных и их визуализации через библиотеку Javascript.

При этом доступных видео-инструкций или текстовых инструкций для чайников нет (где сказали бы: делай раз, делай два, делай три — работает, иначе делай четыре). Это делаем для вот этого, это для — этого. По факту есть набор инструкций, в которых часть шагов подразумеваются как очевидные.

Развертывать кастомную визуализацию мы будем для Docker & Docker-Compose на среде Ubuntu 20.04. На window заниматься этим сразу не советую, т.к. возможно придется плясать с бубном.


Канал в телеграме Apache Superset BI:

Apache Superset BI - это современное корпоративное веб-приложение для бизнес-аналитики. Open-Source система визуализации данных


Основные источники для статьи

В своих попытках построить и задеплоить кастомную визуализацию я опирался на следующие источники. Больше всего мне помогла официальная инструкция от Superset, частично некоторые советы из Superset Slack помогли выйти из тупика.

  1. So, You Want to Build a Superset Viz Plugin…
  2. Apache Superset — Manage Custom Viz Plugins in Production
  3. Superset UI
  4. https://github.com/apache-superset/superset-ui
  5. Superset Doc — Building Custom Viz Plugins
  6. https://github.com/nielsen-oss/superset-viz-plugins

Superset Meetup: Developing and Deploying Custom Visualization Plugins in Superset

Custom Visualization Superset Stack

В этом разделе будут кратко описаны некоторые технологии/инструменты, которые могут пригодиться как в процессе разработки плагинов, так и для автоматизации CI/DI поставки и сборки контейнеров. Я приведу их краткое описание, пометив звездочкой* те, которые сам использовал.

Yeoman*

Yeoman — пакет npm, написанный на Node.js, который позволяет сгенерировать шаблонный код, т.е. автоматизирует работу по созданию одной и той же конструкции кода (создавать контроллеры, модели, миграции, сиды, тесты и т.д.). У YeoMan есть репозитории с генераторами. Берёте генератор -> генерируете -> получаете шаблонный код -> профит.

chromatic.com

Chromatic предназначен для разработки пользовательского интерфейса. Можно настроить непрерывную интеграцию с Storybook.

storybook.js.org

Storybook — это инструмент с открытым исходным кодом для изолированной разработки UI компонентов. Он упрощает разработку пользовательского интерфейса, тестирование и документацию, т.к. запускается отдельно от вашего приложения.

Storybook предоставляет нам интерактивную площадку пользовательского интерфейса для наших компонентов.

The UI component explorer. Develop, document, & test React, Vue, Angular, Web Components, Ember, Svelte & more!

Storybook — это среда разработки компонентов пользовательского интерфейса. Он позволяет просматривать библиотеку компонентов, просматривать различные состояния каждого компонента, а также в интерактивном режиме разрабатывать и тестировать компоненты.

NPM*

Определение npm

npm — это менеджер пакетов для платформы Node.JS (JavaScript). Он размещает модули так, чтобы узел мог их найти, и разумно управляет конфликтами зависимостей. Пакет в Node.js содержит все файлы, необходимые для модуля. Модули — это библиотеки JavaScript, которые вы можете включить в свой проект.

package.json

У любого проекта, использующего Node.js, должен быть package.json файл.

package.json — это манифест вашего проекта, который включает пакеты и приложения, от которых он зависит.

Внутри package.json вы почти всегда найдете метаданные, относящиеся к проекту — независимо от того, является ли это веб-приложение, модуль Node.js или даже простая библиотека JavaScirpt. Эти метаданные помогают идентифицировать проект и служат базой для пользователей и участников при получении информации о проекте.

package.json всегда структурирован в JSON формате. Наличие зависимостей в вашем проекте package.json позволяет проекту устанавливать версии модулей, от которых он зависит. Запустив команду установки npm install внутри проекта, вы можете установить все зависимости, перечисленные в проекте.

npm может устанавливать пакеты в локальном или глобальном режиме. В локальном режиме он устанавливает пакет в node_modules папку в вашем родительском рабочем каталоге. Это местоположение принадлежит текущему пользователю.

package-lock.json

Наличие package-lock.json в проекте не обязательно. package-lock.json автоматически создается для любых операций, когда npm изменяет node_modules дерево или package.json. Он описывает точное дерево, которое было сгенерировано, так что последующие установки могут генерировать идентичные деревья, независимо от промежуточных обновлений зависимостей.

package-lock.json нельзя опубликовать, и он будет проигнорирован, если будет найден в любом месте, кроме корневого проекта.

package-lock.json: записывает точную версию каждого установленного пакета, что позволяет вам повторно установить их. Будущие установки смогут построить идентичное дерево зависимостей.

package.json: записывает минимальную версию, необходимую вашему приложению. Если вы обновите версии определенного пакета, это изменение не будет отражено здесь.

Webpack.js.org

webpack представляет собой сборщик статических модулей для современных приложений JavaScript. Когда webpack обрабатывает ваше приложение, он внутренне строит граф зависимостей, который отображает каждый модуль, необходимый вашему проекту, и генерирует один или несколько пакетов.

Yarn*

Yarn — это менеджер пакетов для вашего кода.

Lerna

Lerna — это инструмент, который оптимизирует рабочий процесс по управлению многопакетными репозиториями с помощью git и npm. Lerna — это библиотека, которая предоставляет инструменты для управления структурой нескольких репозиториев внутри одного репозитория путем разделения подмножеств репозитория на их собственные «вспомогательные» репозитории. Структурированный таким образом репозиторий называется монорепо.

Lerna используется в основном в крупных проектах, которые со временем становится трудно поддерживать. Это позволяет разделить код на более мелкие управляемые репозитории и абстрагироваться от общего кода, который можно использовать в этих вспомогательных репозиториях.

Typescript

Typescript — это язык с открытым исходным кодом, который основан на JavaScript, путем добавления определений статических типов. Типы предоставляют способ описания формы объекта, обеспечивая лучшую документацию и позволяя TypeScript проверять правильность работы вашего кода.

Babel

Babel — это компилятор JavaScript. Babel построен на системе плагинов, которая анализирует ваш современный JavaScript в AST (абстрактное синтаксическое дерево) и переписывает его в версию, которая может быть интерпретирована браузером.

ESLint

ESLint — анализирует статически ваш код, чтобы быстро находить проблемы. ESLint встроен в большинство текстовых редакторов, и вы можете запускать ESLint как часть вашего конвейера непрерывной интеграции.

Jest

Jest — это фреймворк для модульного тестирования JavaScript и React-приложений. Jest был создан в Facebook. С помощью Jest можно проверить приходят ли свойства в компонент и корректно ли они отображаются через создание snapshots. В первый запуск теста создаётся файл snapshot. Далее можно посмотреть созданный файл и проверить, соответствует ли отрендеренный компонент ожидаемому результату.

Разбираемся с Dockerfile для Apache Superset

В этом разделе будет описан Dockerfile из репозитория https://github.com/apache/superset/blob/master/Dockerfile в виде комментариев к блокам файла Dockerfile, либо к отдельным строчкам. Пока описано только 2 раздела, второй раздел с Node.js нужен для деплоя Custom Viz.

Предварительные требования для разработки плагина для Apache Superset

В этом разделе я опишу, что нужно установить до начала разработки плагина:

  1. Docker
  2. Docker-Compose
  3. Node.js
  4. npm
  5. yarn
  6. Yeoman
  7. Visual Studio Code (или другой редактор кода)

Установку Docker и Docker-Compose можно посмотреть в статье: Как развернуть Apache Superset с помощью Docker-Compose

Node.js и npm нужно установить определенной версии, лучше ориентироваться на версию из Dockerfile, т.е. Node.js — 14, а npm — 7 версия.

Пакет yarn устанавливается через команду npm install yarn.

Yeoman и пакет @superset-ui/generator-superset устанавливаются двумя последовательными командами:

Создание Apache Superset Plugin и подключение его в dev среду

Забегая немного вперед, я создавал две директории с проектом superset и пакетом superset-ui рядом друг с другом:

Шаг 1. Развертываем продуктивную среду с помощью docker-compose

Как это сделать, можно посмотреть в статье Как установить на Ubuntu Apache Superset — VPS Beget (см. раздел Как развернуть Apache Superset с помощью Docker-Compose).

Для установки версии 1.1.0 используйте команды:

После установки и запуска продуктивной среды сразу же запустим дев-среду, чтобы проверить, что все работает, до начала разработки плагина. Итак, переходим в папку superset-frontend:

и запускаем команду установки всех зависимостей и пакетов:

После того, как все ок, запускаем дев сервер:

Переходим по ссылке http://localhost:9000, где мы должны увидеть dev-superset (логин и пароль либо admin/admin, либо соответствует вашей продуктивной среде).

После проверки нажмите в консоли Ctrl + C.

Шаг 2. Скачиваем репозиторий superset-ui

Шаг 3. Генерация проекта с помощью Yeoman:

После этого выполняем следующие команды:

Шаги по выбору нужных параметров для Yeoman можно найти в исходной документации https://superset.apache.org/docs/installation/building-custom-viz-plugins.

Мои шаги были следующими:

Шаг 1

Шаг 2

Шаг 3.

Шаг 4.

Шаг 5.

Шаг 6.

Шаг 7.

Yeoman создаст следующую файловую структуру — каркас плагина:

Сам плагин находится в исходном состоянии. Это означает, что он не собран для продуктива (не выполнена команда yarn build), но его можно запустить в среде разработки. Про build плагина будет расказано дальше, а сейчас запустим среду разработки и подключим в нее наш новый плагин.

Для этого сначала нам необходимо добавить три строчки в два файла package.json и MainPreset.js. То, что нужно внести в эти файлы, лучше глянуть в сгенерированном файле README.md внутри плагина.

Шаг 4.1. Добавляем в файл package.json

Шаг 4.2. Добавляем в файл MainPreset.js

Вторая строка:

Шаг 4.3. Делаем npm link в директории superset/superset-frontend/

В директории superset/superset-frontend/node_modules/@superset-ui должна появиться подпапка plugin-chart-my-viz с ярлычком (стрелкой):

Шаг 5. Повторно запускаем dev-server:

В директории superset-frontend запускаем команду:

Переходим по ссылке http://localhost:9000, где мы должны увидеть наш новый плагин:

Если подсунуть плагину данные, то выглядит это примерно так:

Apache Superset Plugin — Yarn Build. Билдинг плагина визуализации

Шаг 6. Далее переходим в корень папки superset-ui и вызываем команду билда

До build плагина его структура выглядит так:

Процесс сборки плагина выглядит примерно так (в списке вы должны увидеть название вашего плагина):

Шаг 7. Проверяем собрался ли наш новый плагин

Переходим в директорию superset-ui/plugins/plugin-chart-my-viz и в ней должны появиться подпапки esm и lib:

Теперь полная структура всех файлов и папок плагина выглядит так:

В первый раз у меня не забилдился плагин. По этому поводу у меня есть три гипотезы:

  1. Я использовал название plugin-chart-hello-world
  2. Плагин не забилдился из-за npm-link
  3. Что-то с версиями пакетов node или yarn

Шаг 8. Публикация плагина в репозиторий npmjs.com

Для публикации плагинов в npmjs необходимо зарегистрироваться и создать организацию внутри аккаунта, я для тестирования создал @superset-charts. Далее в папке с построенным плагином запускаем команду:

И далее вбиваем все, что нас попросит npm (логин и пароль):

Далее запускаем команду:

И вбиваем параметры пакета (название, с учетом организации, версию, лицензию). Я вбил следующие параметры:

Далее публикуем плагин в открытый доступ командой:

Успешный процесс нам отобразит следующую инфу:

Шаг 9. Проверка плагина в репозитории npmjs.com

Можете создать отдельную папку plugin_test и в ней запустить команду:

Ваш плагин установится в папку и в директории plugin_test/node_modules/@superset-charts/plugin-chart-my-viz вы должны увидеть следующие папки:

Если состав папок отличается, то возможно что-то пошло не так.

Шаг 10. Подготовка сборки нового образа

Далее идем в проект superset в папку superset-frontend и меняем наши старые добрые файлики package.json и MainPreset.js.

Шаг 10.1. Меняем файл package.json на опубликованный в npmjs пакет

Шаг 10.2. Меняем файл MainPreset.js на опубликованный в npmjs пакет

Билдим образ — Docker Image Build for Apache Superset Plugin

Шаг 11. Останавливаем контейнеры docker-compose

Переходим в директорию superset и запускаем команду:

Шаг 12. Билдим образ

Запускаем команду:

Берем со стола бубен, который недавно использовали при запуске dev-server и надеемся, что образ соберется 😉

Для сборки образа superset нужна оперативная память. Докер иногда ее не освобождает. И можете получить следующее сообщение:

Мне помогает в этих ситуациях рестарт, как самый простой путь. Возможно есть команда докера — напишите в комментариях, пожалуйста.

При хорошем исходе вы получите ответ:

Почему-то в процессе сборки superset за собой оставляет кучу промежуточных образов.

Шаг 13. Меняем файл docker-compose-non-dev.yml в директории superset

Далее запускаем команду:

Находим название и версию нашего образа. Открываем файл docker-compose-non-dev.yml и правим строчку:

Шаг 14. Пересобираем контейнеры

Далее запускаем команду:

Получаем результат в продуктиве:

Другие полезные команды Docker

Удалить все образы:

Остановить все контейнеры:

Удалить все контейнеры:

Дополнительный способ добавления плагина в родной образ superset

Добавить плагин, можно в образ, который лежит на hub docker. Для этого нужно написать свой докер-файл:

Ошибки и их решения при разработке Custom Plugin Apache Superset

#1 не запускается dev-server

Статус:  не решено 

В первый раз запуска дев-сервера все работало нормально. В последующие разы тестирования последовательности наткнулся на следующую ошибку:

Причем это без кастомного плагина.

Ссылка на Slack Apache Superset: Module not found: Error: Can’t resolve >>>

Решение: todo

#2 — не запускается dev-server с построенным плагином

Статус:  не решено 

Решение: Точное решение не нашел, но переустановив все пакеты на следующий день, все заработало. Есть подозрение, что один из пакетов, который приходит в папку node_modules периодически сбоит (возможно криво зафиксирована версия) и менеджер пакетов качает не тот пакет из npm репозитория.

3
0
Оставьте комментарий! Напишите, что думаете по поводу статьи.x