Пример развертывания DocHub

Цели примера

1. Показать как можно разделить DocHub на различные репозитории в зависимости от их назначения
2. Показать как реализовать контейнеризацию выделенных репозиториев на базе Docker
3. Показать как можно оптимизировать работу с контейнерами DocHub на примере docker compose

Суть подхода

В процессе работы с DocHub стало понятно, что процесс наполнения архитектурного озера данных и процесс реализации и доработки метамодели - это разные процессы. Данные для озера нужно катить часто, а метамодель нужно катить редко и проверять качественно. Если они развертываются в рамках одного процесса, то мы получаем конфликт между скоростью и качеством. Так же нужно учитывать что этими процессами могут заниматься разные люди.

После того как в DocHub была реализована возможность разделения метамодели и данных, было принято решение переструктурировать подход управления DocHub.

Что было сделано

Мы определили четыре основных компонента DocHub, каждый из которых, в первую очередь, подразумевает свой процесс разработки, тестирования и развертывания

1. Метамодель (metamodel)
2. Озеро данных (manifest)
3. Бэкенд (backend)
4. Фронтенд (frontend)

Такой подход позволяет нам:

1. Управлять разными процессами по разному
2. Существенно ускорить процесс выкатки изменений (в первую очередь озера данных)
3. Улучшить качество метамодели, так как в процесс можно встроить этап полноценного тестирования

Чего нет в примере, но чтобы хотелось

1. Валидации обновления озера данных в рамках пайплайна развертывания
2. Вынесение плагинов в отдельный компонент

Описание примера

Все каталоги находящиеся в корневой директории можно рассматривать как отдельные репозитории.

Файловая структура примера

|- backend              - конфигурация бэкенда
|  |- dochub            - подмодуль ссылающийся на оригинальный репозиторий DocHub (https://github.com/RabotaRu/DocHub)
|  |- Dockerfile        - настройка контейнера Docker
|  |- entrypoint.sh     - запуск бэкенда
|- frontend             - конфигурация фронтенда
|  |- dochub            - подмодуль ссылающийся на оригинальный репозиторий DocHub (https://github.com/RabotaRu/DocHub)
|  |- Dockerfile        - настройка контейнера Docker
|  |- entrypoint.sh     - наполнение переменных для разных стендов DocHub, запуск nginx со статикой фронтенда
|  |- nginx.conf        - конфигурация nginx, важный нюанс: фронтенд проксирует бэкенд наружу, т.е. запросы проксируются с браузера через nginx фронтенда в бэкенд
|- manifest             - манифесты архитектурного озеры данных
|  |- manifest          - подмодуль ссылающийся на репозиторий с примером данных DocHubExampleManifest (https://github.com/ValentinKozlov/DocHubExampleManifest)
|  |- Dockerfile        - настройка контейнера Docker
|  |- nginx.conf        - настройка nginx через который раздаются данные для бэкенда
|- metamodel            - манифесты архитектурного озеры данных
|  |- metamodel         - подмодуль ссылающийся на репозиторий с примером метамодели DocHubExampleMetamodel (https://github.com/ValentinKozlov/DocHubExampleMetamodel)
|  |- Dockerfile        - настройка контейнера Docker
|  |- nginx.conf        - настройка nginx через который раздаются данные для бэкенда
|- docker-compose.yaml  - пакетный запуск контейнеров Docker.
|- README.md            - описание репозитория

Использование

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

1. Клонируйте себе пример git clone --recurse-submodules https://github.com/cu3blukekc/SwampHub.git либо просто клонируйте себе репозиторий, перейдите в него и выполните команды git submodule init && git submodule update. В случае с Windows используйте для клонирования только PowerShell, также на винде не всегда отрабатывает команда git clone --recurse-submodules, поэтому выполните следующие шаги:
   • Выполните команду git clone https://github.com/cu3blukekc/SwampHub.git
   • Перейдите в папку SwampHub cd SwampHub
   • Выполните команду git submodule init
   • Выполните команду git submodule update (выполняется минут 10-15)
2. Создайте в корне пустой файл .env
3. Выполните команду docker-compose up или docker compose up (v2)
4. Откройте браузер и наберите http://localhost:8080/
5. Успех!
6. Празднование успеха!

Обновление подмодулей

Так как в репозитория часть проекта собирается из подмодулей, то для того чтобы их обновить был написан скрипт update.sh. Зайдите в корень репозитория swamp и запустите скрипт. Вы можете обновить каждый репозиторий подключенный сабмодулем вручную. Для этого зайдите в нужный репозиторий и выполните команду git pull, но обратите внимание, что такие репозитории клонируются не на дефолтные ветки, а на конкретные коммиты, поэтому перед обновлением измените ветку на основную.

Удаление подмодулей

1. Удалить секцию подмодуля из .gitmodules
2. Выполнить команду git add .gitmodules
3. Удалить подмодуль из .git/config
4. Из корня репозитория выполнить команду git rm -rf --cached path_to_submodule
5. Удалить папку с подмодулем

Если нужно, что-то поменять на горячую

Для того чтобы сделать reload бэкенда, в DocHub существует отдельная API. Для его работы в backend нужно передать переменную окружения VUE_APP_DOCHUB_RELOAD_SECRET для доступа к перезагрузке данных архитектуры.

1. В файле .env и внесите значение переменной VUE_APP_DOCHUB_RELOAD_SECRET=все что угодно
2. Перезапустите контейнер с backend, если он был запущен
3. Внесите изменения в озеро данных или в метамодель
4. Выполните скрипт reload_backend.sh
5. Проверьте что новые изменения подтянулись на портал DocHub

Вариант установки в Windows

Инструкция развертывания в windows

Запуск проекта

• Запускаем в Oracle VM VirtualBox и переходим в виртуальную машину с именем SwampHub_defaul_* (команда "Показать")
• Вводим логин и пароль: vagrant / vagrant
• Переходим в каталог cd /vagrant
• Запускаем скрипт запуска ./scripts/run.sh
• Запускаем сайт http://localhost:8080

Авторские права

1. Вся работа по настройке контейнеров Docker была выполнена Александром Трубниковым https://t.me/cu3blukekc
2. Примеры репозиториев с метамоделью, данными и текущая инструкция были адаптированы Валентином Козловым https://t.me/i_frog_i.
3. Репозиторий для сборки сервера PlantUML принадлежит Владиславу Маркину https://t.me/vlad_markin и был взят отсюда.