Публичное пространство
SetKit ◾️ Установка и настройка. Обновление (Ubuntu, CentOS)
Текущая версия:
Требования
- ОС: Ubuntu 22.04 и выше (или любые другие семейства Линукс);
- Оперативная память RAM: 1Gb;
- Достаточное место на жестком диске: от 50Гб;
- Установлен агент лицензирования.
Список необходимых портов
Проверка доступности портов от кассы к серверу
№ | № порта | Тип | Назначение |
---|---|---|---|
1 | 5432 | TCP | PostgreSQL |
2 | 5435 | TCP | PostgreSQL (внешний) |
3 | 8081 | TCP | SetKit - базовый порт по умолчанию. В инструкции для примера указан порт 8084, может быть изменен при необходимости. |
4 | 5002 | TCP | artifactory.setmachine |
Установка
Docker
Установка Docker
Требования
- Docker поддерживается только под ОС Линукс.
- Для установки обязательно должны быть включен доступ к сети Интернет. После установки его можно выключить.
- Должен быть установлен агент лицензирования, без него продукт SetKit работать не будет.
- Устанавливается только Docker CE!
- Установка Docker может производиться на любые сборки ОС Linux: CentOS, Fedora, Ubuntu и т.д.
- Данная инструкция выполнена на образах SetRetail Ubuntu 22.04 и SetRetail10 CentOS 7 и полностью подходит для установки на них.
- Если установка производится на чистый образ, учитывайте конфигурации антивирусных программ и политики безопасности вашей сети.
Подготовка Linux или другого ядра к установке Docker
Если вы используете сборку CentOS, или любого другого ядра Линукс, то перед установкой Docker, убедитесь, что у вас присутствует следующее ПО, которое необходимо использовать при настройке или диагностике:
- Midnight Commander;
- Telnet;
- wget;
Пример установки пакетов в чистый образ Linux:
yum install mc
sudo apt install mc
yum install telnet
sudo apt install telnet
yum install wget
sudo apt install wget
Пример установки пакета telnet
- Введите команду установки пакета в зависимости от ОС (CentOS или Ubuntu), в нашем примере CentOS:
yum install telnet
- После загрузки пакета на вопрос
Is this ok [y/d/N]:
введите y → нажмите ENTER.
Проверка свободного места
- Для установки обязательно должны быть включены внешние репозитории
- Проверить наличие свободного места командой
df -h /var /home/
- Для домашней папки /home не менее 10Гб. /dev/mapper/centos-root
- Для общей папки приложений /var не менее 50Гб. /dev/mapper/centos-var
Подготовка
1. Создайте в домашней директории папку setkit
sudo mkdir /home/setkit
2. Создайте папку docker_compose
sudo mkdir /home/setkit/docker_compose sudo chmod -R 777 /home/setkit
3. Переместите присланные файлы конфигурации Docker docker-compose.yml и .env в папку /home/setkit/docker_compose
При копировании из ОС Windows файла .env, всегда обращайте внимание на его наименование. Название файла должно начинаться с точки.
4. Загрузите файлы конфигурации Docker с помощью WinSCP или другим способом в папку /home/setkit/docker_compose
- docker-compose.yml (для версий SetKit 3.X.X и выше).
- env
Откройте на редактирование файл docker-compose.yml и установите подключение к серверу лицензирования:
- license.agentAddress=localhost:8089
- пример адреса, если SetAgent установлен на одном сервере с SetKit.- license.agentAddress=192.168.56.1:8089
- пример адреса, если SetAgent установлен на другом сервере.- В сборке Ubuntu может потребоваться ввод адреса SetAgent в формате http://192.168.56.1:8089
5. Переименуйте файл env в .env
Обратите внимание, что в WinSCP файл с наименованием точки перед расширением отображаться перестанет
6. В файле .env для тега IMAGE_TAG
введите номер последней актуальной версии SetKit. Например: IMAGE_TAG=3.2.3
Сохраните файл.
Основные шаги
- Обязательно производите установку в режиме суперпользователя.
- Если это пользователь не root, тогда произведите логин с правами администратора, выполнив команду
sudo su
с вводом пароля для пользователя.
1. Обязательно выполните команду для удаления старых версий Docker:
sudo yum remove docker \ docker-common \ docker-selinux \ docker-engine
sudo apt-get purge -y docker-engine docker docker.io docker-ce sudo apt-get autoremove -y --purge docker-engine docker docker.io docker-ce sudo umount /var/lib/docker/ sudo rm -rf /var/lib/docker /etc/docker sudo rm /etc/apparmor.d/docker sudo groupdel docker sudo rm -rf /var/run/docker.sock sudo rm -rf /usr/bin/docker-compose
2. Установите необходимые пакеты, выполнив команду:
sudo yum check-update
sudo apt update
3. Установите Docker
curl -fsSL https://get.docker.com/ | sh
Дождитесь окончания процесса.
4. Выполните следующие команды:
sudo curl -L "https://github.com/docker/compose/releases/download/1.26.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo mv /usr/local/bin/docker-compose /usr/bin/docker-compose sudo chmod +x /usr/bin/docker-compose docker-compose --version
5. Запустите docker
sudo systemctl start docker
6. Проверьте, что служба Docker запускается, набрав команду:
sudo systemctl status docker
7. Установите службу docker на автозапуск
sudo systemctl enable docker
8. Произведите авторизацию для учетной записи, которая позволяет выполнить установку SetKit.
Выполните команду:
sudo docker login artifactory.setmachine.ru:5002
- Username: setkit-customers
- Password: lcbGF56_%%#F!
- Процесс ввода пароля не отображается.
- Учетная запись только для установки SetKit.
- Без службы лицензирования и наличия SetID сервис SetKit работать не будет.
Убедитесь, что появилось сообщение Login Succeeded
.
Установка SetKit Docker
1. Перейдите в папку docker_compose, выполнив команду:
cd /home/setkit/docker_compose/
2. Для установки SetKit наберите команду:
sudo docker-compose up -d
Начнется процесс установки. Дождитесь его окончания.
Если при выполнении команды docker-compose up -d
появилась следующая ошибка. Такая ситуация может происходить, когда установка происходит не из под пользователя root в сборке CentOS SetRetail.
Выполните следующие команды и действия для решения запуска Docker:
Установите права (вторая команда именно с точкой):
sudo usermod -aG docker $USER sudo chmod 755 -R .
Пройдите заново авторизацию:
Выполните команду:
docker login artifactory.setmachine.ru:5002
- Username: setkit-customers
- Password: lcbGF56_%%#F!
Запустите контейнер
docker-compose up -d
3. Выполните команду:
sudo reboot
4. После перезагрузки сервера, откройте любой браузер и проверьте, что от неё есть ответ.
Вставьте в строку браузера следующее значение http://IP-адрес сервера SetRetail10:ПОРТ/set-kit/softcheques/1
Если служба ответила сообщением "Мягкий чек не найден", это означает что она работает корректно.
Настройка в SetRetail10
На сервере
1. Откройте Интеграция → кликните Внешние процессинги → кликните .
2. Выберите из левой части списка Мягкие чеки → установите флажок Служба мягких чеков SetKit X → нажмите кнопку .
3. Кликните рядом с процессингом Служба мягких чеков SetKit X.
4. Заполните необходимые поля для мягкого чека и нажмите кнопку .
Значения полей:
- [Адрес сервера SET Kit] - задайте IP-адрес сервера SetRetail10 в формате
http://XXX.XXX.XXX.XXX:ПОРТ
- [Таймаут соединения, мс (по умолчанию 30000 мс)] - время ожидания соединения со службой мягких чеков.
- [Таймаут записи/чтения, мс (по умолчанию 30000 мс)] - время ожидания соединения с базой данных мягких чеков.
- [Префикс мягкого чека] - установите префикс, благодаря которому касса будет распознавать, что введенное значение является мягким чеком.
- [Длина номер мягкого чека (без префикса)] - введите допустимую длину номера мягких чеков.
- [Длины и префиксы номера мягкого чека (через точку с запятой)] - указывается длина и префиксы номеров мягких чеков при включенной настройке Валидировать номер мягкого чека в форме ввода в формате, например:
длина-префикс,префикс;длина-префикс,префикс,префикс
- [Обрезать префикс перед отправкой] - необходимо использовать в случаях хранения номеров заказов без префикса.
- [Разрешить добавление акцизных алкогольных товаров] - возможность добавления алкогольных товаров с вводом акцизных марок на кассе.
- [Производить поиск мягкого чека с индексом своего магазина] - необходимо использовать в случаях, когда нумерация заказов происходит в каждом магазине.
- [Сохранять в чековых данных дополнительную информацию из МЧ] - необходимо использовать в случаях, когда требуется передача дополнительной информации по заказу.
- [Формировать фактический МЧ]- необходимо использовать в случаях, когда требуется отобразить финальный состав заказа в SetKit после фискализации чека.
- [Применять скидки, полученные в составе мягкого чека] - разрешить расчет скидок на товары, добавленные из SetKit.
- [Сохранять номер заказа для позиций, добавленных дополнительно в чек] - возможность присвоения номера заказа к добавленным позициям в случаях добавления или замены товара в заказе.
- [Использовать ставку НДС, указанную в МЧ] - необходимо использовать в случаях, когда требуется передавать ставку НДС из мягкого чека.
- [Спрашивать о целостности заказа] - отображать предупреждение о проверке при вызове мягкого чека с акцизными марками.
- [Запретить замещение карты лояльности из мягкого чека] - необходимо использовать в случаях, когда требуется запретить на кассе редактирование карты лояльности, пришедшей из мягкого чека.
- [Валидировать номер мягкого чека в форме ввода] - если настройка выключена, то не осуществляется проверка номера МЧ в форме ввода на кассе. Если настройка включена, тогда необходимо указать префикс и длину номера мягкого чека в поле Длины и префиксы номера мягкого чека (через точку с запятой).
- [Запретить продажу маркированных товаров] - запрет продажи маркированных товаров при вызове из SetKit.
- [Запретить частичное поднятие заказа] - при включенной настройке, если хотя бы один из товаров заказа не может быть добавлен в чек, весь заказ будет отклонен.
5. Для быстрого вызова поиска мягкого чека, можно сделать функциональную клавишу на прикассовой клавиатуре, для этого перейдите в раздел Кассовый модуль → кликните Кассовое оборудование → войдите в режим редактирования.
6. Назначьте функцию для клавиши Поиск мягкого чека.
На кассе
1. Перейдите во Внешние процессинги и проверьте, что наименование процессинга Служба мягких чеков SetKit X присутствует в списке.
Внимание!
Статус процессинга мягких чеков Службы мягких чеков SetKit X всегда будет в статусе не подключен. Проверка подключения к службе проверяется запросом мягкого чека на кассе.
2. После того как вы убедились, что необходимый процессинг мягких чеков отображается на кассе, перезагрузите кассовый модуль.
Проверка работы SetKit X
Для того чтобы проверить, есть ли обмен данными между кассовым модулем и службой мягких чеков SetKitX, сделайте следующее.
1. Перейдите в режим добавления товара в чек введите префикс мягкого чека и любой номер.
2. Отправьте тестовый запрос на создание мягкого чека с помощью инструментариев по генерации.
Пример запроса для создания мягкого чека
Запрос отправляется по адресу
http://192.168.56.1:8081/set-kit/softcheques/771234
- 77 - префикс мягкого чека
- 1234 - остальные цифры состава штрих-кода мягкого чека
3. Вставьте содержание запроса в тело программы для генерации и отправьте его на сервис мягких чеков.
В поля "code"
и "barcode"
введите штрих-код товара, который есть в товарном справочнике.
{ "guid": "ext-01", "shopNumber": null, "status": "READY_TO_PAYMENT", "dateCreated": 1517481826629, "isEditable": true, "totalPrice": 611, "discountsValue": 0, "additionalInfo": "additional information", "positions": [ { "positionOrder": 1, "code": "4810167000258", "departNumber": 1, "barcode": "4810167000258", "quantity": 2, "unitPrice": 305.5, "vat": 5, "vatValue": 20, "discountValue": 0, "totalPrice": 611, "isFixedPrice": false, "isFixedDiscounts": null, "additionalInfo": "клиент 1. хороший клиент", "positionDiscounts": null } ], "client": { "guid": "0001", "cardNumber": "7000555578975445", "firstName": "Виталий", "middleName": "Олегович", "lastName": "Denisov", "email": "client1_v@mail.ru", "phone": "+7-999-111-22-33", "accumulation": 25000, "bonusBalance": 5000 } }
4. Дождитесь ответа с номером мягкого чека в поле guid.
5. Введите номер мягкого чека из поля guid на кассе для его поиска и нажмите кнопку ВВОД. Если поиск мягкого чека успешный, это означает, что касса полностью готова к работе с сервисом SetKitX.
После ввода номера мягкого чека произойдет добавление товаров в чек.
Если чек уже был оплачен, тогда на экране появится следующее сообщение:
6. Нажмите клавишу для которой назначена функциональная кнопка для поиска мягкого чека и введите его штрих-код без префикса.
Обновление SetKit на ОС Linux
Обновление SetKit на новую версию
1. Перейдите в домашнюю папку Docker, где расположен SetKit
cd /home/setkit/docker_compose/
2. Выполните команду для остановки Docker.
sudo docker-compose stop
3. Запустите Midnight Commander командой mc
→ откройте клавишей F4 на редактирование файл /home/setkit/docker_compose/.env.
4. Введите значение новой версии SetKit в параметр IMAGE_TAG
→ сохраните файл клавишей F2 → выйдите из Midnight Commander клавишей F10 в командную строку.
5. Выполните команду для обновления SetKit:
sudo docker-compose pull
Начнётся процесс загрузки обновления. Дождитесь окончания процесса:
6. Запустите Docker командой:
sudo docker-compose up -d
Обновление SetKit с версии 3.X.X до 4.X.X на CentOS7 и Ubuntu
Обновление с версии 2.Х.Х до 3.Х.Х выполняется аналогичным образом, кроме пунктов:
- в п.11 в файле .env указывается версия 3.Х.Х;
- в п.18 указываются новые значения путей;
- пункты 23-25 выполнять не нужно.
В версии 3.Х.Х включены новые версии компонентов:
Java 11
springBoot2
PostgreSQL 11
Начиная с версии SetKit 4.0.0 включены новые версии компонентов:
PostgreSQL 15
- CR-10316Получение подробных данных проблемы… СТАТУС
- SR-6655Получение подробных данных проблемы… СТАТУС
- Обязательно производите установку в режиме суперпользователя.
- Если это пользователь не root, тогда произведите логин с правами администратора, выполнив команду
sudo su
с вводом пароля для пользователя.
1. Перейдите в командной строке в папку SetKit:
cd /home/setkit/docker_compose/
2. Узнайте имя вашего контейнера:
docker inspect --format='{{.Name}}' $(sudo docker ps -aq --no-trunc)
3. Остановите backend-службу докера командой:
docker-compose stop backend
4. Сделайте резервную копию базы данных SetKit. Дождитесь окончания процесса.
docker exec set-kit_postgres_1 pg_dumpall -U postgres > dump.sql
5. Остановите остальные службы докера командой:
docker-compose stop
6. Из настроечного файла выведите на экран путь к базе данных PostgreSQL командой:
grep -r docker-compose.yml -e 'postgresql'
7. Используя путь к базе данных из предыдущего пункта сделайте резервную копию командой.
Дождитесь окончания процесса копирования.
cp -R /data/setkit/data /data/setkit/data_backup
8. Очистите папку с базой данных Setkit командой:
rm -rf /data/setkit/data/*
9. Наберите команду mc
для запуска Midnight Commander.
10. Перейдите к файлу .env → нажмите клавишу F4.
11. В поле IMAGE_TAG установите значение в соответствии с требуемой версией → нажмите клавишу F2 для сохранения изменений → нажмите клавишу Esc два раза для выхода из редактора.
12. Нажмите клавишу F10 → выберите Да → нажмите Enter для выхода из Midnight Commander.
13. Введите команду для обновления SetKit.
Начнется процесс обновления SetKit, дождитесь его окончания.
docker-compose pull
14. Когда закончится процесс загрузки новой версии, отобразится статус done
.
15. Наберите команду mc
для запуска Midnight Commander.
16. Перейдите к файлу docker_compose.yml → нажмите клавишу F4.
17. Прокрутите файл до секции volumes
со строчками /data/setkit/...
Убедитесь, что значения путей соответствуют указанным:
18. В случае, если значения путей отличаются (например, при обновлении с версии 2.Х.Х до 3.Х.Х) - установите новые значения путей → нажмите клавишу F2 для сохранения изменений → нажмите клавишу Esc два раза для выхода из редактора.
- /data/setkit/logs:/logs - /data/setkit/license:/licenses
19. Нажмите клавишу F10 → выберите Да → нажмите Enter для выхода из Midnight Commander.
20. Выполните команду:
docker-compose up -d postgres
21. Выполните команду для перемещения архива баз данных SetKit:
cp dump.sql /data/setkit/data
22. Выполните команду на восстановление базы данных. Начнется процесс её восстановления, в ходе которого могут появиться сообщения об уже существующих ролях и базах данных, при этом он будет производиться.
docker exec set-kit_postgres_1 psql -U postgres -f /var/lib/postgresql/data/dump.sql
Дождитесь окончания процесса восстановления баз данных.
23. Так как в версии PostgreSQL 15 используется новый тип шифрования пароля scram-sha-256, требуется заново задать пароль для доступа к базе данных с новым типом шифрования.
Выполните команду:
docker exec -it set-kit_postgres_1 psql -U postgres
24. Задайте логин и пароль для доступа к базе данных.
- Пароль должен совпадать с предыдущим.
- При установке SetKit по данной инструкции логин и пароль по умолчанию - postgres/postgres.
- В случае, если данные для доступа отличаются от логина и пароля по умолчанию, они отображаются в файле .env.
ALTER ROLE postgres WITH PASSWORD 'postgres';
25. Введите команду exit
для выхода из консоли → нажмите Enter.
26. Выполните команду для запуска docker, в процессе будет отображено сообщение об обновлении базы данных.
docker-compose up -d
27. Процесс обновления завершен.
Обязательно проверьте работу SetKit:
- Создание чеков
- Поиск мягких чеков.
28. После того, как процесс обновления завершен, удалите резервные копии баз данных:
rm -rf /data/setkit/data_backup/ rm -f /data/setkit/data/dump.sql rm -f /home/setkit/docker_compose/dump.sql
Переход SetKit с ОС CentOS на ОС Ubuntu
1. Проверьте размер папки с PostgreSQL командой:
Внимание!
Общий объем базы данных всегда должен умножаться на 2, чтобы хватило места для бэкапирования.
Например:
- Общий объем файлов базы данных составляет 40Gb. 40 * 2 = 80Gb.
- Таким образом требуется 80Gb для обновления и резервного копирования.
du -hs /data/setkit/data/
2. Выполните команду для создания бэкапа базы данных SetKit на CentOS:
docker exec set-kit_postgres_1 pg_dumpall -U postgres > dump.sql
3. Скопируйте файл dump.sql на жесткий диск.
4. Выполните шаги по установке SetKit на сервер Ubuntu по основной инструкции (глава Установка).
5. После проверки работоспособности SetKit в браузере (пункт 4 главы Установка SetKit Docker) скопируйте файл dump.sql в папку /home/setkit.
6. Выполните команду для перемещения архива баз данных SetKit:
sudo mv /home/setkit/dump.sql /data/setkit/data/
7. Выполните команду на восстановление базы данных. Начнется процесс её восстановления, в ходе которого могут появится сообщения об уже существующих ролях и базах данных, при этом он будет производиться.
sudo docker exec set-kit_postgres_1 psql -U postgres -f /var/lib/postgresql/data/dump.sql
Дождитесь окончания процесса восстановления баз данных.
8. Для проверки подключитесь к БД, используя порт 5435.
9. После завершения процесса восстановления удалите резервную копию базы данных:
sudo rm -f /data/setkit/data/dump.sql
Дополнительная информация
Автоматическая очистка баз данных SetKit под ОС Linux
Настройки находятся в файле /home/setkit/docker-compose.xml
- scheduler.delay=43200000
- с какой задержкой запускается удаление мягких чеков в миллисекундах.- scheduler.maxDays=100
- время "жизни" мягких чеков в днях.- scheduler.maxMinutes=100
- время "жизни" мягких чеков в минутах, если заданы дни, то они приоритетнее.
Прекращение поддержки учетных записей Docker.HUB
- Начиная с 17.12.2020 больше не требуется создавать учётную запись на публичном ресурсе Docker.HUB https://hub.docker.com/.
- Это никак не повлияет на работу SetKit.
- Все клиенты, кто уже использует SetKit должны произвести переключение на новый репозиторий CSI для получения актуальных обновлений.
- Для новых установок SetKit обновлены конфигурационные файлы с новым адресом репозитория.
На сервере, где установлена служба SetKit выполните следующие шаги:
1. Выполните команду для перехода в домашнюю папку SetKit:
cd /home/setkit/docker_compose/
2. Произведите выход из текущей учетной записи Docker.
docker logout
3. Произведите авторизацию для общей учетной записи, которая позволяет подключиться к общему репозиторию SetKit.
Выполните команду:
docker login artifactory.setmachine.ru:5002
- Username: setkit-customers
- Password: lcbGF56_%%#F!
- Процесс ввода пароля не отображается.
- Учетная запись только для установки SetKit.
- Без службы лицензирования и наличия SetID сервис SetKit работать не будет.
Убедитесь, что появилось сообщение Login Succeeded
.
4. В файле /home/setkit/docker_compose/.env для тега IMAGE_TAG
введите номер последней актуальной версии SetKit. Например: IMAGE_TAG=2.0.9
Сохраните файл. (Клавиша F2).
5. В файле /home/setkit/docker_compose/docker-compose.yml измените адреса контейнеров
Установите в следующих секциях значения:
postgres:
- Вместо
crystalservice/set-kit-database:${IMAGE_TAG} - Установите
artifactory.setmachine.ru:5002/set-kit-database:${IMAGE_TAG}
- Вместо
backend:
- Вместо
crystalservice/set-kit-backend:${IMAGE_TAG} - Установите
artifactory.setmachine.ru:5002/set-kit-backend:${IMAGE_TAG}
- Вместо
6. Остановите Docker.
Выполните команду:
docker-compose stop
7. Выполните команду:
docker-compose up -d
Начнется процесс обновления информации из контейнеров CSI. Дождитесь его окончания. Проверьте работу SetKit.
Логирование
- Инструкция актуальна только для версий SetKit до версий 3.0.0.
- Начиная с версии 3.0.0 включать логирование через Tomcat не требуется.
Уровни логирования
- ERROR - минимальный уровень логирования. Только отображение ошибок.
- WARN - средний уровень логирование. Отображение ошибок и предупреждение.
- DEBUG - максимальный уровень логирования. Отображений каждого действия.
Включение логирования
1. Добавьте строку -
logging.level.ru.crystals=WARN
в секцию environment
файла /home/setkit/docker_compose/docker-compose.yml → сохраните файл.
В данном примере произойдет повышение уровня логирования до WARN.
2. Выполните команды для перезапуска Docker:
docker-compose stop docker-compose up -d
3. Перейдите в папку /data/setkit/logs для анализа лог-файлов.
Настройка ротации логирования local_access_log
- SR-4419Получение подробных данных проблемы… СТАТУС
1. Выполните команду для того, чтобы узнать имя контейнера: