Документация

Инструкция по установке программного комплекса DoXML

DoXML — программный комплекс для создания, редактирования, валидации и управления проектной документацией в соответствии с требованиями Минстроя Российской Федерации. Инструкция описывает развёртывание комплекса в инфраструктуре заказчика. В состав входят пользовательское приложение, панель администратора организации, сервер приложений на Java Spring Boot, сервис лицензирования, база данных PostgreSQL, сервер кэширования Redis и объектное хранилище Apache Ozone.

Содержание

  1. Системные требования
  2. Подготовка Docker-образов
  3. Быстрый старт
  4. Подробная установка
  5. Первичная активация и лицензия
  6. Настройка Traefik и SSL
  7. Проверка установки
  8. Управление сервисом

1. Системные требования

  • Операционная система: Ubuntu 22.04 LTS / Debian 12 (рекомендуется)
  • Docker: 24.0 или новее
  • Docker Compose: v2 (плагин docker compose)
  • Процессор: минимум 4 ядра (рекомендуется 8+ для production)
  • Оперативная память: минимум 8 ГБ (рекомендуется 16 ГБ)
  • Дисковое пространство: минимум 120 ГБ SSD (рекомендуется NVMe, 250+ ГБ)
  • Сеть: доступ в интернет для загрузки образов и получения SSL-сертификатов Let's Encrypt (или локальный registry для закрытого контура)

2. Подготовка Docker-образов

Программный комплекс поставляется в виде готовых Docker-образов от вендора. Для получения образов:

  1. Получите от вендора адрес реестра образов, имя пользователя и пароль (или персональный токен доступа).
  2. Авторизуйтесь в реестре: 
    docker login registry.example.com
  3. Загрузите образы: 
    docker pull registry.example.com/doxml/webapp/backend:latest
docker pull registry.example.com/doxml/webapp/frontend-client:latest
docker pull registry.example.com/doxml/webapp/frontend-control-panel:latest
docker pull registry.example.com/doxml/webapp/ocr-service:latest

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

3. Быстрый старт

Рекомендуемый способ — использование готового пакета установки:

  1. Распакуйте пакет: 
    tar -xzf doxml-onprem-install.tar.gz
cd doxml-onprem
  2. Проверьте Docker: 
    docker --version
docker compose version
  3. Скопируйте и заполните переменные окружения: 
    cp infrastructure/.env.example infrastructure/.env
nano infrastructure/.env
  4. Запустите установку: 
    cd infrastructure
docker compose -f docker-compose.onprem.yml --env-file .env up -d

Обязательные параметры в .env

  • ONPREM_DOMAIN — домен установки (например, doxml.company.local)
  • TRAEFIK_ACME_EMAIL — email для Let's Encrypt
  • POSTGRES_PASSWORD — надёжный пароль PostgreSQL
  • REDIS_PASSWORD — пароль Redis
  • JWT_SECRET — секретный ключ для подписи JWT
  • SPRING_PROFILES_ACTIVE=prod — обязательно для production
  • APP_TOPOLOGY — топология развёртывания в инфраструктуре заказчика
  • APP_FRONTEND_URL=https://doxml.company.local — публичный URL клиентского приложения

4. Подробная установка

Шаг 1: Подготовка файлов окружения

  1. Перейдите в infrastructure/.
  2. Скопируйте .env.example → .env.
  3. Заполните обязательные параметры из раздела выше.

Шаг 2: Запуск инфраструктурных сервисов

cd infrastructure
docker compose -f docker-compose.onprem.yml --env-file .env up -d postgres redis ozone traefik

Дождитесь, пока PostgreSQL пройдёт healthcheck.

Шаг 3: Запуск сервера приложений и сервиса лицензирования

docker compose -f docker-compose.onprem.yml --env-file .env up -d backend license-service

Шаг 4: Запуск клиентских приложений

docker compose -f docker-compose.onprem.yml --env-file .env up -d frontend-client frontend-control-panel

Шаг 5: Запуск OCR-сервиса

docker compose -f docker-compose.onprem.yml --env-file .env up -d ocr-service

5. Первичная активация и лицензия

При первом старте экземпляр системы создаёт служебную организацию с идентификатором AA22A и учётную запись администратора экземпляра системы.

  1. Откройте в браузере https://{ONPREM_DOMAIN}/setup.
  2. Укажите реквизиты организации.
  3. Запросите лицензионный ключ у вендора или вставьте полученный ключ.
  4. После установки ключа синхронизируется выданный публичный идентификатор организации и активируется продукт.

Важно: до появления действующей лицензии обычные пользовательские функции заблокированы, но администратор экземпляра системы может войти в панель управления организацией и обновить ключ.

6. Настройка Traefik и SSL

Traefik, встроенный в docker-compose.onprem.yml, автоматически:

  • терминирует HTTPS на 443;
  • получает и обновляет сертификаты Let's Encrypt;
  • маршрутизирует запросы на сервер приложений, клиентское приложение и панель управления организацией.

Закрытый контур

Если Let's Encrypt недоступен, используйте собственные сертификаты и настройте Traefik через дополнительные хранилища сертификатов TLS и промежуточное программное обеспечение. Для внутреннего тестирования допускается HTTP, но эксплуатация требует HTTPS.

7. Проверка установки

Статус контейнеров

cd infrastructure
docker compose -f docker-compose.onprem.yml --env-file .env ps

Проверка API

curl https://api.{ONPREM_DOMAIN}/actuator/health
curl https://{ONPREM_DOMAIN}/api/v1/public/instance-setup

Проверка базы данных

docker compose -f docker-compose.onprem.yml --env-file .env exec postgres psql -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT version();"

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

Просмотр логов

cd infrastructure
docker compose -f docker-compose.onprem.yml --env-file .env logs -f backend
docker compose -f docker-compose.onprem.yml --env-file .env logs -f frontend-client

Остановка, запуск, перезапуск

docker compose -f docker-compose.onprem.yml --env-file .env stop
docker compose -f docker-compose.onprem.yml --env-file .env start
docker compose -f docker-compose.onprem.yml --env-file .env restart

Обновление

  1. Сделайте резервную копию базы и файлов.
  2. Получите новые образы от вендора.
  3. Пересоздайте контейнеры: 
    docker compose -f docker-compose.onprem.yml --env-file .env pull
docker compose -f docker-compose.onprem.yml --env-file .env up -d

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

  • PostgreSQL: ежедневные дампы через pg_dump.
  • Ozone: резервная копия объектного хранилища.
  • Каталог license/: ключ license.key и install-secret.txt не попадают в дамп БД и должны храниться отдельно.

Версия документа: 2.0
Дата обновления: 2026

Скачать документ