Подготовить среду
Для развертывание экземпляра сервиса необходимо подготовить инфрастуктуру:
- загрузить образ сервиса 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
- Запросить у администратора базы создание отдельной базу или роль с правом выполнять миграции и создавать базу данных приложения.
- Уточните адрес базы данных для формирования
DATABASE_URL, доступный именно из Docker-контейнера. - Сформируйте строку
DATABASE_URLс именем базы, логином и паролем. Если пароль содержит специальные символы, сначала кодируйте их, как описано ниже. - Проверьте, что контейнер сможет подключиться к базе и к 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.