РАЗВЕРТЫВАНИЕ СИСТЕМЫ. DOCKER

Подготовка к установке (Linux)

Для установки ПО PLAN-R необходимо выполнить следующую последовательность операций:

1. Убедится, что установлено необходимое ПО Docker (19.03.0+) и docker-compose (1.27.1+)

# docker --version
Docker version 24.0.7, build afdd53b

# docker-compose –version
Docker Compose version v2.23.3-desktop.2

2. Рекомендуется подготовить структуру каталогов для развертывания системы.

Рекомендуемая структура каталогов:

• /opt/dppm/ – каталог текущей развернутой системы
• /opt/dppm/distr – каталог для хранения скачанных дистрибутивов
• /opt/dppm/postgres_dump – каталог для бэкапов базы данных

Создайте структуру каталогов выполнив следующие команды.

# mkdir /opt/dppm && mkdir /opt/dppm/distr && mkdir /opt/dppm/postgres_dump
# cd /opt/dppm
# ls -lha

total 16K
drwxr-xr-x 4 root root 4.0K Mar 28 14:05 .
drwxr-xr-x 5 root root 4.0K Mar 28 14:05 ..
drwxr-xr-x 2 root root 4.0K Mar 28 14:05 distr
drwxr-xr-x 2 root root 4.0K Mar 28 14:05 postgres_dump

3. Переместите скачанный дистрибутив в каталог /opt/dppm/distr/

# mv <path*to_distr>/planr*<_version_>.zip /opt/dppm/distr/
# cd /opt/dppm/distr
# ls -la

total 2638584
drwxr-xr-x 2 root root       4096 Mar 28 14:05 .
drwxr-xr-x 4 root root       4096 Mar 28 14:05 ..
-rw-r-xr-x 1 root root 2701895280 Mar 28 14:05 planr_XXX.x.zip

4. Извлеките файлы из архива в каталог /opt/dppm, выполнив команды в соответствующем порядке (пароль можно получить по запросу на почту support@dppm.pro)

# unzip -P <_password_> /opt/dppm/distr/planr\_<_version_>.zip -d /opt/dppm/
# ls -lha

Извлечение файлов приложения из архива

5. После распаковки архива переходим в каталог /opt/dppm/images для загрузки docker образов командой ./load.sh. После успешной загрузки образов каталог ./images можно удалить.

• cd /opt/dppm/images
• ./load.sh

Распаковка образов PLAN-R

Установка PLAN-R (Linux)

1. Выполняем подготовку к установке (8.2.1 Подготовка к установке (Linux))
2. Переходим в директорию /opt/dppm/planr/, редактируем файл с переменными среды .env (8.4 Конфигурирование системы)
3. Выполняем старт системы с помощью ./start.sh

Успешный старт системы

Установка PLAN-R (Windows)

1. Скачать и установить Docker Desktop следуя инструкциям по ссылке https://docs.docker.com/desktop/install/windows-install
2. Создать директорию для развертывания, например С:\Plan-r.
3. Скачать архив с последней версией дистрибутива.
4. Разархивировать содержимое архива в директорию С:\Plan-r с помощью специальных программ-архиваторов например WinRar. Во время разархивации программа должна запросить пароль (пароль можно получить через запрос в службу поддержки support@dppm.pro).
5. Запустить консоль PowerShell от имени администратора и выполнить следующие команды:
   • cd C:\Plan-r \planr-r _ <_version_>\images
   • Get-ChildItem .\ *.tar | foreach {docker load --input $ _.FullName}

Загрузка образов системы в Docker

6. Перейти в директорию C:\Plan-r \planr_<version>\planr. Сконфигурировать систему путём изменения файла с переменными среды .env под свои нужды (8.4 Конфигурирование системы). Запустить PLAN-R следующей командой.

• cd C:\PLAN-R\planr_403.0\planr\
• docker compose --env-file ./.env -p "planr" up -d

Старт приложения PLAN-R

7. Зайти в приложение Docker Desktop и убедится, что всё работает корректно.

Работающее приложение PLAN-R

Обновление системы

Подготовка к обновлению системы

1. Перед проведением обновления системы, рекомендуется выполнить резервное копирование (см. п. 8.4.2.1 Создание бэкапа базы данных перед обновлением)
2. Перейти в папку разворота системы по умолчанию /opt/dppm/planr. Остановить систему, сделать бэкап текущей конфигурации PLAN-R, перенеся текущий каталог разворота в каталог /opt/dppm/planr_old/planr

• cd /opt/dppm/planr
• ./stop.sh
• mv /opt/dppm/planr/planr opt/dppm/planr_old/ planr

Бэкапирование предыдущих настроек

3. Переместите скачанный дистрибутив в каталог /opt/dppm/distr/

• $ mv <path_to_distr> /planr_ <version>.zip /opt/dppm/distr/
• $ cd /opt/dppm/distr
• $ ls -lha

Перемещение скачанного архива в каталог

4. Извлеките файлы из архива в каталог /opt/dppm, выполнив команды в соответствующем порядке (пароль можно получить по запросу на почту support@dppm.pro)

• unzip -P <password> /opt/dppm/distr/planr_<version>.zip -d /opt/dppm/
• ls -lha

Извлечение файлов приложения из архива

5. После распаковки архива переходим в директорию ./images для загрузки docker образов командой ./load.sh. После успешной загрузки образов каталог ./images можно удалить.

• cd /opt/dppm/images_<version>
• ./load.sh

Распаковка образов PLAN-R

Обновление системы PLAN-R (Linux)

1. Выполняем подготовку к обновлению системы (8.3.2 Обновление системы PLAN-R (Linux))
2. Выполняем слияние актуального файла конфигурации .env и файла конфигурации созданного ранее (находящегося в директории /opt/dppm/planrold/planr_ <_version>). Вносим необходимые изменения в переменные среды если требуется (8.4 Конфигурирование системы)
3. Запускаем систему командой ./start.sh

Успешный старт системы

Переменные среды

Файл переменных среды. env (Environment variables если используется Portainer) содержит в себе все настройки системы, которые применяются при старте. После изменения файла с переменными среды, для применения настроек, нужно выполнить ./start.sh для вступления изменений в силу. Описание всех переменных среды приведено в таблице ниже.

Таблица 4. Описание значений переменной COMPOSE_PROFILES

Для контроля запуска нужных сервисов используется переменная COMPOSE_PROFILES (https://docs.docker.com/compose/profiles/).

Например, если планируется использовать внешнюю базу данных, то её профиль необходимо исключить, тогда переменная примет следующие значения

• COMPOSE_PROFILES=main,redis,rabbitmq,logging

Описание доступных профилей для старта указано в следующей таблице.

Таблица 5. Значение переменной COMPOSE_PROFILES

Настройка бэкапов системы

Создание бэкапа базы данных перед обновлением

Для создания бэкапов базы данных перед обновлением можно использовать несколько способов:

• Создание бэкапа с помощью скрипта ./dump.sh входящим в комплект поставки Для этого выполните скрипт dump.sh. Данный скрип создаст бэкап базы данных на текущий момент в директории /opt/dppm/postgres_dump
  • ./dump.sh -p /opt/dppm/postgres_dump

Создание бэкапа базы данных перед обновлением

• Создание бэкапа встроенными средствами Для этого переходим в директорию /opt/dppm/postges_dump (создаём, если её не существует) и выполняем следующую команду.
  • docker exec postgres /bin/bash -c "export PGPASSWORD=planr && pg_dump -U planr planr" | gzip -9 > planr_latest.sql.gz
  • ls -lha

Создание бэкапа базы данных перед обновлением

Настройка бэкапов по расписанию

Для созданию бэкапов по расписанию необходимо добавить скрипт dump.sh в таблицу исполнения скриптов по расписанию crontab. Параметры запуска скрипта можно посмотреть, выполнив ./dump.sh -h.

Параметры запуска скрипта dump.sh

Пример использования скрипта в crontab приведен ниже. В данном случае скрипт выполняется каждую ночь в 3:00, делает бэкап в директорию /opt/dppm/postgres_dump/ с периодом ротации 14 (Это означает что в папке всегда будет хранится 14 актуальных бэкапов) и количеством файлов, которые не удалятся в любом случаи – 5.

Исполнение скрипта по расписанию

Восстановление базы данных из бэкапа

Для восстановления базы данных из бэкапа используем скрипт ./restore.sh. Пример использования скрипта по восстановлению базы данных из бэкапа представлен на рисунке ниже.

Восстановление базы из файла бэкапа

Способы аутентификации

Настройка аутентификации через OIDC на примере keycloack

Настройка интеграции с OIDC провайдерами настраивается с помощью переменных среды в файле ./planr/.env. Описание необходимы переменных среды можно найти в таблице (см. Таблица 4. Описание значений переменной COMPOSE_PROFILES )

Заходим в keyclocak, создаём новый realm с именем Planr, либо используем уже существующий. Переходим в созданный или существующий Realm, нажимаем “Realm setting” и скачиваем файл “OpenID Endpoint Configuration”.

Скачивание файла OpenID Endpoint Configuration

Переходим во вкладку “Clients” и создаем клиента. Во вкладке Capability Setting обязательно включить “Client authentication”. В вкладке “Login Settings” обязательно указать Valid redirect URLs (тут нужно указать FQDN хоста, на котором развернут PLAN-R, например https://PLAN-R.ru/*).

Создание клиента для Planr realm

Включение Client authentication

Указание Valid redirect URLs

Переходим к настройкам переменных среды в файле ./planr/.env. Открываем ранее скачанный файл OpenID Endpoint Configuration.json (справа на скриншоте) и сопоставляем данные для авторизации с переменными среды. Значение переменной OPENDID_CLIENTID и OPENID_CLIENTSECRET можно взять из Keycloak, перейдя в нужный Realm, далее открыть созданного ранее клиента planr и перейти на вкладку “Сredentials”. Переменная OPENID_CALLBACKURL должна содержать FQDN хоста, на котором развернут PLAN-R в формате http://PLANR-HOST/api/v1/auth/openid.

После сохранения настроек применить изменения командой ./start.sh

Настройка переменных среды для для авторизации через OIDC

Если все настроено правильно при входе должна появиться иконка OpenID.

Кнопка OpenID.

Настройка SSO Kerberos

Для включения SSO авторизации Kerberos нужно выполнить следующие условия:

• KERBEROS_ENABLED=true (включение доступной стратегии авторизации kerberos)
• KERBEROS_CONF_PATH=/etc/krb5.conf (абсолютный или относительный путь к файлу конфигурации krb5.conf)
• KERBEROS_KEYTAB_PATH=/etc/krb5_multi.keytab (абсолютный или относительный путь к keytab файлу (ссылка генерация keytab файла)).
• COMPOSE_PROFILES=all,kerberos (добавить профиль kerberos для запуска необходимого сервиса для авторизации).
• Убедится, что в DNS существует A и RTP запись для сервера, где будет расположен PLAN-R
• Настроить браузеры для SSO

При соблюдении всех условий при авторизации должна появится кнопка “kerberos”, при нажатии на которую происходит аутентификация по сеансу операционной системы.

Кнопка аунтификации по сеансу операционной системы

Генерация keytab файла

SPN (Service Principal Name) — уникальный идентификатор экземпляра сервиса. SPN используется аутентификацией Kerberos для сопоставления экземпляра сервиса с учетной записью сервиса (service logon account). Это позволяет клиентским приложением аутентифицироваться в роли сервиса, даже не зная имени пользователя.

До того, как аутентификация Kerberos сможет использовать SPN для аутентификации сервиса, SPN должен быть привязан к учетной записи, которая будет использоваться для входа. SPN может быть привязан только к одной учетной записи. Если учетная запись, привязанная к SPN, изменяется, то необходимо заново выполнить привязку.

Когда клиент хочет воспользоваться сервисом, он находит экземпляр сервиса и составляет SPN для этого экземпляра, далее использует этот SPN для аутентификации.

Keytab-файл — это файл, содержащий пары Kerberos принципалов и их ключей (полученных с использованием Kerberos пароля). Эти файлы используются для аутентификации в системах, использующих Kerberos, без ввода пароля. Если пароль принципала изменится, то keytab-файл необходимо будет сгенерировать заново.

Windows DC

1. Создание пользователя для привязки SPN (Необходимо запретить смену пароля и не ограничивать его срок действия, иначе придётся перегенерировать keytab-файл)

Создание пользователя на windows DC

2. В командной строке доменного контролера выполнить привязку SPN к учётной записи

• setspn -A HTTP/plan-r.ru planr-sso

Привязка SPN к созаной учетной записи

3. Создание и привязка keytab файла происходит с помощью следующей команды где:

• ktpass -princ HTTP/plan-r.ru@IV.DP.RU -mapuser planr-sso -pass Pa$$word -ptype KRB5_NT_PRINCIPAL -out C:\planr.keytab

где:

• -princ — имя принципала, содержащее SPN и Kerberos-область (realm);
• -mapuser — пользователь, к которому привязывается SPN;
• -pass — пароль пользователя;
• -ptype — указывает тип принципала (рекомендуется KRB5_NT_PRINCIPAL);
• -out — путь и имя генерируемого файла.

Создание Keytab файла

4. Заходим в оснастку ADUC и убеждаемся, что для созданной учетной записи “User logon name” сменилось на имя привязанной SPN. Включена поддержка 128 и 256 битного шифрования для Kerberos.

Проверка учетной записи

Samba DC

1. Создание пользователя для привязки SPN к пользователю.

• samba-tool user create --random-password planr-sso
• samba-tool user setexpiry planr-sso –noexpiry
• samba-tool spn add HTTP/plan-r.ru planr-sso

Создание и привязка SPN к пользователю

2. Генерируем keytab файл с помощью следующей команды.

Генерация keytab фалйла для samba DC

3. Перенести файл на сервер и указать путь к нему с помощью переменной KERBEROS_KEYTAB_PATH