Инструкция по установке

Для XRM Director версии 1.0.1

Данная инструкция описывает только развертывание XRM Director на сервере, где `Docker` и `Docker Compose` уже установлены и готовы к работе.

Установка Docker на российские ОС описана отдельной инструкцией и в данный документ не входит.

Что будет развернуто

В составе поставки используются два контейнера:

• backend — серверная часть XRM Director;

• frontend — веб-интерфейс XRM Director.

Используемые образы:

• xrmtech/xrm-director-backend:beta_0.2.7

• xrmtech/xrm-director-frontend:beta_0.2.7

  Если для версии XRM Director 1.0.1 должны использоваться другие теги контейнерных образов, замените их в файле docker-compose.yml до запуска.

Предварительные условия

Перед началом убедитесь, что:

• установлена РЕД ОС 8;

• пользователь имеет права root или может выполнять команды через sudo;

• Docker установлен;

• Docker Compose установлен;

• сервер имеет доступ к реестру контейнерных образов;

• свободны порты 80/tcp и 8001/tcp;

• настроена сетевая связность с брокерами OpenUDS;

• подготовлены учетные данные администратора для подключения к брокерам OpenUDS.

  Рекомендуется заранее проверить DNS, синхронизацию времени и доступность целевых брокеров OpenUDS.

Структура каталогов

Развертывание выполняется, например, в каталоге /opt/xrmd.

Итоговая структура:

/opt/xrmd/
├── docker-compose.yml
└── backend/
    ├── settings.py
    ├── logs/
    ├── plandata/
    └── db/

---

Шаг 1. Подготовка каталогов

Рекомендуется заранее создать рабочие каталоги:

sudo mkdir -p /opt/xrmd/backend/logs
sudo mkdir -p /opt/xrmd/backend/plandata
sudo mkdir -p /opt/xrmd/backend/db

Этот шаг не является строго обязательным: при использовании `bind mount` Docker обычно может создать отсутствующие каталоги автоматически. Однако рекомендуется создать их заранее, чтобы избежать проблем с правами доступа, владельцем каталогов и записью данных приложения.

При необходимости назначьте права текущему пользователю:

sudo chown -R $USER:$USER /opt/xrmd

Перейдите в каталог развертывания:

cd /opt/xrmd

---

Шаг 2. Подготовка файла settings.py

Создайте файл /opt/xrmd/backend/settings.py со следующим содержимым:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    ADMIN_USER: str = "admin"
    ADMIN_PASSWORD: str = "admin"
    BROKER_CONN_TIMEOUT: int = 20  # Default timeout for broker connections
    
    class Config:
        env_file = ".env"

settings = Settings()

Назначение параметров

• ADMIN_USER — логин администратора XRM Director;

• ADMIN_PASSWORD — пароль администратора XRM Director;

• BROKER_CONN_TIMEOUT — таймаут подключения к брокерам OpenUDS в секундах.

  Значения admin / admin допустимы только для первичного запуска или тестового стенда. Для рабочей эксплуатации рекомендуется заменить их до запуска.

  Пример измененной конфигурации:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    ADMIN_USER: str = "xrmd-admin"
    ADMIN_PASSWORD: str = "Сложный_Пароль"
    BROKER_CONN_TIMEOUT: int = 20
    
    class Config:
        env_file = ".env"

settings = Settings()

---

Шаг 3. Подготовка файла docker-compose.yml

Создайте файл /opt/xrmd/docker-compose.yml со следующим содержимым:

services:
  backend:
    image: xrmtech/xrm-director-backend:beta_0.2.7
    ports:
      - "8001:8001"
    volumes:
      - ./backend/settings.py:/app/settings.py
      - ./backend/logs:/app/logs
      - ./backend/plandata:/app/plandata
      - ./backend/db:/app/db

  frontend:
    image: xrmtech/xrm-director-frontend:beta_0.2.7
    ports:
      - "80:80"

networks:
  default:
    name: xrm-network

Что делает данный файл

• публикует веб-интерфейс на порту 80;

• публикует backend API на порту 8001;

• подключает постоянные каталоги с конфигурацией, журналами и данными;

• создает сеть Docker xrm-network.

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

  ---

Шаг 4. Проверка SELinux

В РЕД ОС 8 может использоваться SELinux. Если он включен в режиме Enforcing, контейнерам может потребоваться дополнительная настройка доступа к примонтированным каталогам.

Проверьте текущий режим:

getenforce

Если возвращается Enforcing, назначьте контекст для каталога backend:

sudo chcon -Rt container_file_t /opt/xrmd/backend

Этот шаг особенно важен, если backend не видит `settings.py` или не может записывать данные в каталоги `logs`, `plandata`, `db`.

Шаг 5. Настройка сетевого доступа

Если на сервере включен firewalld, откройте необходимые порты:

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=8001/tcp
sudo firewall-cmd --reload

Проверка:

sudo firewall-cmd --list-ports

Шаг 6. Запуск XRM Director

Из каталога /opt/xrmd выполните команду:

docker compose up -d

После запуска будут выполнены:

• создание сети xrm-network;

• загрузка контейнерных образов;

• создание контейнеров backend и frontend;

• запуск сервисов в фоновом режиме.

Проверьте состояние контейнеров:

docker compose ps

Оба сервиса должны находиться в состоянии `Up`.

Просмотр журналов

Общий просмотр:

docker compose logs

Журналы backend:

docker compose logs backend

Журналы frontend:

docker compose logs frontend

Просмотр в реальном времени:

docker compose logs -f

Проверка опубликованных портов

ss -tulnp | grep -E ':80|:8001'

Проверка веб-интерфейса

Откройте в браузере:

http://<IP-адрес_или_FQDN_сервера>/

---

Шаг 8. Первый вход

Если в settings.py оставлены значения по умолчанию, используйте:

• логин: admin

• пароль: admin

После входа рекомендуется:

1. проверить доступность backend;

2. проверить сетевую связность с брокерами OpenUDS;

3. выполнить тестовое подключение к брокеру.

   Не оставляйте стандартные учетные данные в рабочем контуре.

---

Управление сервисом

Остановка

cd /opt/xrmd
docker compose down

Остановка без удаления контейнеров

docker compose stop

Повторный запуск

docker compose start

Перезапуск

docker compose restart

---

Обновление

Перед обновлением рекомендуется сохранить резервную копию каталога /opt/xrmd/backend.

Типовой порядок обновления:

cd /opt/xrmd
docker compose down
docker compose pull
docker compose up -d

Если обновление требует смены тегов образов, сначала внесите изменения в docker-compose.yml.

После обновления проверьте:

• состояние контейнеров;

• журналы backend и frontend;

• доступность веб-интерфейса;

• сохранность данных в каталогах db, plandata, logs.

---

Резервное копирование

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

• /opt/xrmd/docker-compose.yml;

• /opt/xrmd/backend/settings.py;

• /opt/xrmd/backend/db/;

• /opt/xrmd/backend/plandata/;

• при необходимости /opt/xrmd/backend/logs/.

Пример архивирования:

sudo tar -czf /opt/xrmd-backup-$(date +%F).tar.gz /opt/xrmd

---

Типовые проблемы

Контейнеры не запускаются

Проверьте:

docker compose ps
docker compose logs

Частые причины:

• ошибка в settings.py;

• заняты порты 80 или 8001;

• отсутствует доступ к реестру образов;

• SELinux блокирует доступ к каталогам.

Порт 80 уже используется

Проверьте, какой процесс занимает порт:

sudo ss -tulnp | grep ':80'

Если порт занят, измените публикацию frontend, например:

  frontend:
    image: xrmtech/xrm-director-frontend:beta_0.2.6
    ports:
      - "8080:80"

После этого веб-интерфейс будет доступен по адресу:

http://<IP-адрес_сервера>:8080/

Backend не может писать в каталоги

Проверьте права:

ls -la /opt/xrmd/backend

Проверьте режим SELinux:

getenforce

При необходимости повторно назначьте контекст:

sudo chcon -Rt container_file_t /opt/xrmd/backend

Нет подключения к OpenUDS-брокерам

Проверьте:

• сетевую маршрутизацию;

• DNS-разрешение имен;

• корректность учетных данных;

• значение BROKER_CONN_TIMEOUT.

При необходимости увеличьте таймаут:

BROKER_CONN_TIMEOUT: int = 30

После изменения конфигурации перезапустите backend:

cd /opt/xrmd
docker compose restart backend

---

Краткая схема установки

1. Подготовить каталог /opt/xrmd.

2. Создать settings.py.

3. Создать docker-compose.yml.

4. При необходимости настроить SELinux.

5. Открыть порты 80/tcp и 8001/tcp.

6. Выполнить docker compose up -d.

7. Проверить состояние контейнеров и журналы.

8. Выполнить первый вход и заменить пароль администратора.

---

Результат

После выполнения шагов XRM Director будет развернут на РЕД ОС 8 в контейнерном исполнении и готов к первичной настройке и подключению к брокерам OpenUDS.

Проверка успешного запуска

После завершения развертывания рекомендуется дополнительно проверить состояние контейнеров.

Выполните команду:

docker ps -a

Пример вывода:

CONTAINER ID   IMAGE                                      COMMAND                  CREATED      STATUS                    PORTS                                         NAMES
d2735dcd514a   xrmtech/xrm-director-frontend:beta_0.2.7   "/docker-entrypoint.…"   6 days ago   Up 24 seconds             0.0.0.0:80->80/tcp, [::]:80->80/tcp           xrmd_install-frontend-1
d5add673f488   xrmtech/xrm-director-backend:beta_0.2.7    "uvicorn main:app --…"   6 days ago   Up 24 seconds             0.0.0.0:8001->8001/tcp, [::]:8001->8001/tcp   xrmd_install-backend-1

Если контейнеры `frontend` и `backend` находятся в состоянии `Up`, это означает, что сервисы успешно запущены и доступны для дальнейшей настройки.

Если один из контейнеров находится в состоянии Exited или Restarting, необходимо проверить журналы:

docker compose logs