Установка при помощи Docker

к сведению

Для работы с Docker-контейнерами необходимо установить Docker и Docker Compose.

Запуск платформы lsFusion с помощью Docker Compose

• Скачайте файл compose.yaml с центрального сервера в выбранную папку (будем называть её $FUSION_DIR$). Этот файл содержит настройки для запуска трёх контейнеров:

  • PostgreSQL
  • Сервер приложений
  • Веб-клиент

• Настройка compose.yaml (опционально):

  • Если требуется изменить параметры запуска (например, использовать другую версию контейнера или настроить переменные окружения), отредактируйте файл compose.yaml в соответствии с документацией Docker.
  • Параметры запуска сервера приложений также можно задавать при помощи переменных среды контейнера - в атрибуте environment. К примеру, чтобы изменить локаль сервера на русскую, а также задать своё значение Xmx, напишите:

    environment:
      - USER_SETLANGUAGE=ru
      - USER_SETCOUNTRY=RU      
      - JAVA_OPTS=-Xmx10g

    При поиске параметров запуска в переменных среды Spring автоматически преобразует их к верхнему регистру и заменяет точки на символы подчёркивания. В примере выше значения переменных среды подставятся в соответствующие параметры: user.setLanguage и user.setCountry.
  • Доступные образы контейнеров lsFusion:
    • Сервер
    • Клиент

• Запуск контейнеров:

  Перейдите в папку $FUSION_DIR$ и выполните команду:

  docker-compose up -d

  После завершения запуска веб-клиент будет доступен по адресу: http://localhost:8080/.

• Работа с файлами проекта:

  • После первого запуска в папке $FUSION_DIR$ будут созданы подпапки:

    • docker-client-conf — конфигурация клиента.
    • docker-db — данные базы данных.
    • docker-server — файлы сервера.

    Эти папки монтируются в соответствующие контейнеры.

  • В папку docker-server поместите модули на языке lsFusion (файлы .lsf или папки с ними), а также дополнительные ресурсы (отчёты, Java-файлы, изображения, CSS, JS и т.д.). В этой же папке находятся серверные логи и файл settings.properties.

---

Создание и запуск Docker-образа вашего проекта

Если ваш проект наследует Maven-модуль платформы lsFusion logics, вы можете использовать встроенные инструменты для создания Docker-образа и генерации файла compose.yaml.

Создание Docker-образа

• Сборка образа:

  Сборка Docker-образа привязана к фазам Maven и активируется профилем docker.

  • На фазе install образ собирается и загружается в локальное хранилище.
  • На фазе deploy образ загружается в публичный реестр (например, Docker Hub).

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

  mvn install -P assemble,docker

  Если вы хотите собрать образ на основе uber-jar с включенным в него сервером lsFusion, добавьте профиль embed-server:

  mvn install -P assemble,embed-server,docker

  По умолчанию создается образ, специфичный для архитектуры и операционной системы Docker daemon. Для сборки мульти-архитектурного образа (linux/amd64 и linux/arm64), необходимо добавить профиль multiarch. Работает только на фазе deploy:

  mvn deploy -P assemble,docker,multiarch

• Загрузка образа в публичный реестр:

  Чтобы собрать образ и загрузить его в Docker Hub, выполните:

  mvn deploy -P assemble,docker

  или (для uber-jar с сервером):

  mvn deploy -P assemble,embed-server,docker

• Настройка имени образа:

  По умолчанию имя образа имеет вид: local/<artifactId>:<version> (artifactId, version - значения соответствующих тэгов в файле pom.xml модуля проекта). Вы можете переопределить часть имени или имя целиком через свойства Maven в pom.xml:

  <properties>
      <docker.image.namespace>foo</docker.image.namespace>
      <docker.image.repository>bar</docker.image.repository>
      <docker.image.tag>1.0</docker.image.tag>
      <!-- или -->
      <docker.image.fullName>foo/bar:1.0</docker.image.fullName>
  </properties>

Генерация и использование compose.yaml

• Автоматическая генерация:

  • При сборке проекта одной из приведённых выше команд с профилем docker Maven автоматически создаёт файл compose.yaml.
  • Файл генерируется с подставленными версией платформы lsFusion и именем Docker-образа вашего проекта.
  • Файл сохраняется в папке target или по пути, указанному в свойстве Maven docker.compose.outputDirectory. Также содержимое файла выводится в консоль после сборки.

• Запуск сгенерированного compose.yaml:

  Запуск и настройка аналогичны шагам, описанным в разделе Запуск платформы lsFusion с некоторыми особенностями:

  • Имя проекта Docker Compose по умолчанию равно значению тэга artifactId. Чтобы генерировалось другое имя проекта, переопределите свойство Maven docker.compose.projectName.

---

Обновление версии PostgreSQL

В compose.yaml зафиксирована основная версия PostgreSQL. Основные версии PostgreSQL несовместимы между собой по формату данных на диске, поэтому после смены версии образа контейнер БД не запустится, пока база не будет мигрирована.

Начиная с версии 18 образ PostgreSQL хранит данные каждой версии в отдельной подпапке (например, 18/docker) и монтирует папку данных по пути /var/lib/postgresql (подробнее). В версиях до 18 данные лежали в корне папки docker-db, которая монтировалась по пути /var/lib/postgresql/data. Поэтому при переходе с версии 17 и ниже в compose.yaml, помимо версии образа, меняется и путь монтирования:

  db:
    image: postgres:18
    volumes:
      - ./docker-db:/var/lib/postgresql

При последующих переходах между версиями 18 и выше путь монтирования не меняется — только версия образа.

warning

Перед миграцией любым из способов убедитесь, что у вас есть свежая резервная копия базы (например, копия папки docker-db, снятая при остановленных контейнерах).

Мигрировать базу можно одним из следующих способов:

• Дамп и восстановление — рекомендуемый способ для большинства установок: новый кластер инициализируется образом штатно, а данные загружаются в него стандартным pg_dumpall:

  docker compose exec db pg_dumpall -U postgres > backup.sql   # при работающей старой версии;
                                                               # файл создаётся рядом с compose.yaml
  docker compose down
  # переименуйте папку docker-db (например, в docker-db-old) - старые данные останутся
  # резервной копией, а новый контейнер создаст чистый кластер; обновите compose.yaml
  docker compose up -d db
  docker compose exec -T db psql -U postgres < backup.sql
  docker compose up -d

• Скрипт миграции — для больших баз, когда дамп и восстановление занимают слишком много времени. Скрипт предназначен для стандартной установки, описанной на этой странице. Скачайте с центрального сервера скрипт pg-migrate.bat (Windows) или pg-migrate.sh (Linux) вместе с pg-migrate-container.sh в папку $FUSION_DIR$. Пропишите в compose.yaml новую версию образа (и, при переходе с 17 и ниже, новый путь монтирования), после чего запустите скрипт. Скрипт автоматизирует шаги, специфичные для Docker-образа: останавливает контейнеры, делает резервную копию папки docker-db (в docker-db-backup), определяет исходную версию и раскладку данных и после миграции снова запускает контейнеры. Саму миграцию выполняет штатный pg_upgrade. Пользовательские настройки postgresql.conf скрипт не переносит. Старый кластер останется в подпапке docker-db со старой версией — удалите его вместе с резервной копией после проверки работоспособности.

Для нестандартных конфигураций (репликация, изменённые образы или раскладка данных) используйте штатную процедуру обновления PostgreSQL.