Порядок подготовки проекта к системе сборки
Любой проект должен быть подготовлен для автоматической сборки с использованием конвеера CI/CD. Для этого в структуру проекта должны быть внесены соответствующие изменения. Код проекта должен поддерживать конфигурирование через переменные окружения, с использованием dotenv или аналогичной библиотеки.
Начальное пополнение проекта
В структуру проекта должны быть добавлены следующие файлы и директории:
- contrib - набор вспомогательных файлов для сборки пакета - шаблоны сервисов, конфигурации веб серверов и т.п.
- debian - набор рецептов для сборки Debian пакета
- Makefile - основной сборочный сценарий проекта
- build.sh - специальный файл обновляющий историю изменений и запускающий сборку. Может использоваться для локальной сборки пакетов
- .env - Переменные окружения, используемые при сборке проекта в распространяемый debian пакет
- .env.develop - Переменные окружения, используемые при настройке стенда
- .env.example - Все доступные переменные окружения. Может включаться в документацию проекта.
- .env.local - Локальные переменные при локальной сборке и запуске проекта
Набор файлов шаблонов доступен для скачивания с корпоративного GIT репозитория. В шаблонах файлов в качестве имени проекта используется слово dummy, его требуется заменить на корректное имя проекта согласно его пути в репозитории GitLab. Путь анализируется от корня репозитория и не учитывает лидирующие пути содержащие слова back и front в имени проекта. Все прямые слеши (символ /) заменяются на тире (символ -). Если в пути проекта присутствует суффикс, содержащий слова front или back, то к имени проекта добавляется суффикс -frontend или -backend, соответственно. Например, если репозиторий имеет путь cok/lms/front то полное имя проекта будет иметь вид cok-lms-frontend, а если репозиторий имеет путь cok/video-store, то полное имя проекта будет иметь вид cok-video-store. Имя проекта, его тип, ветка репозитория отражаются при сборке как соответствующие переменные окружения и могут использоваться в шаблонах конфигурации.
Переменные окружения
При сборке проекта определен ряд переменных окружения, которые автоматически подставляются в файлы конфигурации и файлы .env с параметрами окружения проекта. Основные переменные при сборке проекта:
- PROJECT_NAME - Короткое имя проекта, без суффикса
- PROJECT_FULL_NAME - Полное имя проекта с суффиксом типа проекта
- PROJECT_TYPE - Тип проекта - пустое значение, значения frontend или backend
- PROJECT_BRANCH - Собираемая ветка проекта. Для стендов - имя ветки указывается без префикса stand/
- DB_HOST - Адрес сервера баз данных
- DB_PORT - Порт сервера баз данных
- DB_NAME - Наименование базы данных на сервере
- DB_USER - Имя пользователя для сервера баз данных
- DB_PASSWORD - Пароль пользователя для сервера баз данных
- DB_SCHEME - Схема на сервере баз данных. Параметр задан только для баз данных совместимых с PostgreSQL!
- BACKEND_SERVICE - Адрес бакенд сервера, значение берется из файла конфигурации .env после сборки проекта
- PUBLISH_TYPE - Тип публикации проекта, возможные значения: none, public, private.
Если требуется провести подствановку переменных в файл конфигурации времени сборки, используется синтаксис %VAR%, где VAR - имя переменной.
Секреты и служебная информация
Информация представляющая собой конфиденциальные данные, такие как логины, пароли, ключи и идентификаторы сервисов не должна напрямую фигурировать в файлах конфигурации проекта. Все служебные данные, которые требуется помещать в переменыне окружения на этапе сборки, задаются в виде секретов Jenkins.
Для обращения к секрету используется следующий синтаксис .env файла - %SECRET_<NAME>%, где <NAME> - имя секрета для собираемого проекта. Секреты в Jenkins имеют формат именования <PROJECT_NAME>_<NAME> в нижнем регистре. Таким образом, использование подстановки %SECRET_AUTH_ID% для проекта cok/lms/frontend будет искать значение секрета Jenkins с именем cok-lms_auth_id.
Рекомендуется выделять отдельный домен Jenkins для каждого сервиса/группы сервисов в Jenkins для точечного управления полномочиями на их просмотр и изменение. Тип секрета Jenkins указывается как Text Secret.