Подготовить среду

Для развертывание экземпляра сервиса необходимо подготовить инфрастуктуру: - загрузить образ сервиса querion\salary-slip:<version> в локальный registry хоста, на котором разворачивается система - готовый к работе экземпляр PostgreSQL и параметры подключения (логин, пароль имя базы данных, если база данных не создана, то пользователь должен обладать ролью создания базы данных, сервис создаст необходимую базу данных самостоятельно при запуске) - секретный ключ ENCRYPTED_KEY

Ниже приведён основной вариант: приложение запускается в Docker, а PostgreSQL работает отдельно.

Установите Docker

Установите Docker Engine для Linux и плагин Docker Compose по инструкциям для своего дистрибутива. Если используете группу docker, настройте права по послеустановочной инструкции.

Проверьте команды:

docker version
docker compose version

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

docker login registry.example.com:5000

Подробная информация доступна в официальной справке docker login.

Синхронизируйте системное время

Коды TOTP зависят от точного времени. Контейнеры Docker используют часы хоста, в том числе если вы управляете ими через Portainer. Включите автоматическую синхронизацию времени на хосте и устройстве с приложением-аутентификатором.

На Linux с systemd и установленной службой NTP проверьте состояние синхронизации:

timedatectl status
sudo timedatectl set-ntp true
timedatectl status

После включения дождитесь, пока в выводе появятся System clock synchronized: yes и NTP service: active. Включённая служба сама по себе не подтверждает, что часы уже синхронизировались. Если служба NTP не установлена или не запускается, настройте синхронизацию времени средствами своего дистрибутива.

Часовой пояс и переменная TZ меняют отображение времени, но не синхронизируют системные часы. Если код TOTP не подходит, проверьте синхронизацию на хосте и устройстве-аутентификаторе, затем дождитесь нового кода и введите его. Если вход временно заблокирован после неверных попыток, дождитесь окончания блокировки.

Подготовьте PostgreSQL

  1. Запросить у администратора базы создание отдельной базу или роль с правом выполнять миграции и создавать базу данных приложения.
  2. Уточните адрес базы данных для формирования DATABASE_URL, доступный именно из Docker-контейнера.
  3. Сформируйте строку DATABASE_URL с именем базы, логином и паролем. Если пароль содержит специальные символы, сначала кодируйте их, как описано ниже.
  4. Проверьте, что контейнер сможет подключиться к базе и к 1С, если будете сразу настраивать интеграцию.

Для новой установки используйте отдельную пустую базу: текущая начальная схема предназначена для чистой базы данных. Существующая база разработки с прежней историей миграций автоматически не преобразуется. Не очищайте и не пересоздавайте существующую базу ради установки.

Пул подключений приложения

Пул — это набор подключений к PostgreSQL, которые приложение повторно использует. Параметр pool_max_conns задаёт верхний предел подключений для одного экземпляра приложения; соединения открываются по мере необходимости. Это ограничение не задаёт число сотрудников или пользователей.

Используйте pool_max_conns=32 как значение для первой проверки в DATABASE_URL:

DATABASE_URL=postgres://salary_slip_user:REPLACE_WITH_URL_ENCODED_PASSWORD@db.example.net:5432/salary_slip?sslmode=require&pool_max_conns=32

Если в URL уже есть параметры после ?, добавьте новый через &. Например, ?sslmode=require&pool_max_conns=32. После изменения DATABASE_URL пересоздайте контейнер приложения: внутренний перезапуск панели не перечитывает переменные окружения.

Сумма подключений приложения (сервиса) зависит от числа одновременно работающих экземпляров и максимума пула каждого из них. Например, два экземпляра с пулом 32 могут открыть до 64 подключений. При определении количества подключений PostgreSQL учитывайте нагрузка от других приложений и административных инструментов, а также серверные резервы PostgreSQL. Сверьте общее количество с max_connections и зарезервированными слотами; настройка описана в документации PostgreSQL 15. Изменение max_connections требует перезапуска PostgreSQL, отдельно от пересоздания контейнера приложения.

Специальные символы в пароле

В строке подключения символы пароля, которые имеют специальное значение в URL, нужно записать в виде %XX. Например, @ кодируется как %40, : — как %3A, а % — как %25. Это правило описано в документации PostgreSQL о строках подключения в формате URI.

Кодируйте только значение пароля до вставки в URL. Например, пароль Example@2026:50% станет Example%402026%3A50%25:

DATABASE_URL=postgres://salary_slip_user:Example%402026%3A50%25@db.example.net:5432/salary_slip?sslmode=require&pool_max_conns=32

Не кодируйте разделители URL вокруг пароля. Кодирование меняет запись в строке подключения, но не сам пароль в PostgreSQL.

Создайте файлы запуска

Создайте рабочий каталог на хосте с Docker. Сохраните в нём compose.yaml и .env из примеров ниже. Замените поясняющие значения на выданные поставщиком реквизиты до запуска.

Пример compose.yaml

services:
  salary-slip:
    image: ${SALARY_SLIP_IMAGE:?-querion/salary-slip:latest}
    user: "10001:10001"
    restart: unless-stopped
    environment:
      DATABASE_URL: ${DATABASE_URL:? УКАЖИТЕ КОРРЕКТНЫЙ DATABASE_URL}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY:? ЗАДАЙТЕ КОРРЕКТНЫЙ 32-значный ENCRYPTED_KEY}
      LISTEN_ADDR: 0.0.0.0
      PORT: "8080"
      NODE_ID_FILE: /app/data/node-id.json
      TRUSTED_PROXIES: ${TRUSTED_PROXIES:-}
      ADMIN_LOGIN: ${ADMIN_LOGIN:-}
      ADMIN_TEMP_PASSWORD: ${ADMIN_TEMP_PASSWORD:-}
      # Для лицензированной установки Linux: подготовьте копию UUID хоста.
      # LICENSE_HOST_SYSTEM_UUID_FILE: /run/license-host/system_uuid
    ports:
      - "${HOST_BIND_IP:-127.0.0.1}:${HOST_PORT:-8080}:8080"
    volumes:
      - salary-slip-data:/app/data
      # Для коммерческой активации лицензии необходимо монтирование  раздела с системным, 
      # раскомментируйте bind и переменную LICENSE_HOST_SYSTEM_UUID_FILE выше.
      # - type: bind
      #   source: /etc/salary-slip/license-host/system_uuid
      #   target: /run/license-host/system_uuid
      #   read_only: true
      #   bind:
      #     create_host_path: false

volumes:
  salary-slip-data:

Пример .env

SALARY_SLIP_IMAGE=registry.example.com/company/salary-slip:release-tag
DATABASE_URL=postgres://salary_slip_user:REPLACE_WITH_URL_ENCODED_PASSWORD@db.example.net:5432/salary_slip?sslmode=require&pool_max_conns=32
ENCRYPTION_KEY=REPLACE_WITH_GENERATED_BASE64_KEY
HOST_BIND_IP=127.0.0.1
HOST_PORT=8080
TRUSTED_PROXIES=
ADMIN_LOGIN=REPLACE_WITH_ADMIN_LOGIN
ADMIN_TEMP_PASSWORD=REPLACE_WITH_TEMPORARY_PASSWORD

registry.example.com/company/salary-slip:release-tag — пример, а не адрес реестра. Замените его точной ссылкой на образ и тег, которые предоставил поставщик. Образ должен соответствовать архитектуре хоста.

В DATABASE_URL укажите адрес, доступный контейнеру. Для базы на другом хосте не используйте адрес localhost. Имя пользователя, пароль, узел и базу в примере тоже замените. Если пароль содержит специальные символы, кодируйте их по правилу выше.

Сгенерируйте ENCRYPTION_KEY командой:

// Создание ключа в среде Linux:

openssl rand -base64 32
// Создание ключа в среде Windows:

$bytes = New-Object byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
[Convert]::ToBase64String($bytes)

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

Если пароль или другое строковое значение содержит символ $, заключите всё значение в одинарные кавычки в .env, чтобы Compose прочитал знак буквально. См. подстановку переменных в Compose.

Переменные ADMIN_LOGIN и ADMIN_TEMP_PASSWORD нужны только для создания первого администратора при запуске на пустой базе. После первого входа удалите их из .env и пересоздайте контейнер. Укажите временный пароль длиной не менее 12 символов.

Ограничьте доступ к .env: в нём хранятся пароль базы и ключ шифрования. Не используйте показанные значения-заполнители при реальном запуске.

Для лицензированной установки подготовьте стабильную копию UUID хоста и включите два закомментированных параметра в основном compose.yaml. См. установку в Docker. В режиме DEMO подключение UUID не требуется.

После подготовки перейдите к установке в Docker.