ВНИМАНИЕ! Если вы уже используете Docker-окружение для USERSIDE 3.12, установленное до 8 мая 2019 г., то Вам обязательно необходимо ознакомиться с разделом обновления с устаревшей версии 3.12! Если Вы разворачивали Docker-окружение до 8 мая 2019 г., если оно содержит отдельно каталог с окружением userside-docker и отдельно каталог с системой /opt/userside и резервными копиями /opt/backup, то ваше окружение считается устаревшим!

Описание

Данный проект представляет собой набор образцов конфигурационных файлов и скриптов для запуска Docker-бандла системы ERP USERSIDE. Все необходимые для работы ERP USERSIDE образы уже собраны со всеми необходимыми зависимостями и настройками и размещены в Docker HUB. Вы можете на основе данных образцов собрать свой бандл, используя Docker composer либо испльзуя другие, удобные вам, инструменты оркестрации. Вы также можете воспользоваться образцами как есть и получить работающую систему ERP USERSIDE без каких либо дополнительных действий. Мы полностью полагаемся на ваше понимание работы контейнеризации в Linux, работы Docker, docker compose, swarm и других систем, которые вы собираетесь использовать.

Данные образцы Docker-окружения распространяются «как есть» без каких либо гарантий. Мы также не оказываем техническую поддержку по вопросам установки, настройки и обслуживания Docker и связанных с ним инструментов. Если вы не знакомы с Docker, то вам следует воспользоваться классическим примером установки ERP USERSIDE на Linux-сервер.

В пределах этой инструкции используется понятие «версия Docker-бандла», которая соответствует минимальной версии USERSIDE, способной работать на этой версии бандла. Например, на версии Docker-бандла 3.13 может работать USERSIDE версий 3.13, 3.14, 3.15, а на версии Docker-бандла 3.16 может работать USERSIDE 3.16, 3.17 и т.д., пока не появится новая версия бандла для какой-то очередной версии USERSIDE. Не путайте версию Docker-бандла с версией USERSIDE.

Требования

Необходимо, чтобы на вашем сервере был установлен Docker CE, а также Docker compose. Для этого у Вас должен быть сервер под управлением 64-разрядной ОС Linux. Инструкции по установке Docker CE и Docker compose, в зависимости от дистрибутива и версии Linux, Вы найдете на официальном сайте: Docker CE, Docker-compose.

Мы рекомендуем использовать GIT-репозиторий для получения новых версий бандлов. Для этого необходимо установить систему управлениями версиями GIT. Однако, если Вы по каким-то причинам предпочитаете не использовать репозиторий, Вы можете просто загружать архивы с наборами файлов (бандл) вручную, как будет сказано ниче.

Установка

Все инструкции по установке содержатся в репозитории по адресу https://github.com/userside/userside-docker

Видеоинструкция

По ссылке https://youtu.be/9S3LsXvIulc находится видеоинструкция установки USERSIDE с использованием Docker-окружения. В данной видеоинструкции используется домен docker.userside.demo, А-запись которого соответствует IP-адресу сервера, на котором производится установка.

Эксплуатация

Большинство часто используемых команд сформированы в короткие команды (макросы), выполнить которые можно используя вызов

sudo make <имя_команды>

Список команд

up - запускает бандл
down (или stop) - останавливает бандл
install - составная команда, которая выполняет все действия, необходимые для развёртывания и запуска бандла, а также установки USERSIDE
userside-install - команда, которая только запускает скрипт-установщик внутри контейнера (возможно пригодится, если установка предыдущей командой закончилась неудачно и нужно повторить запуск установщика)
update - составная команда, которая выполняет все действия, необходимые для обновления как docker-образов окружения, так и самой системы USERSIDE
uninstall - составная команда, которая выполняет удаление бандла. При этом файлы userside, резервные копии и файлы базы данных остаются
log - команда, отображающая все логи бандла в реальном времени (выход ctrl+c)

Также Вы можете использовать и остальные команды в отдельности, указанные в этом файле. Кроме того, Вы можете использовать команду docker-compose напрямую, чтобы выполнять команды бандла, не предусмотренные этим файлом. Изучите файл Makefile чтобы получить больше информации о подобном запуске.

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

Резервное копирование и восстановление

Если Вам необходимо вручную создать резервные копии базы данных и файлов, Вы можете запустить макрос:

make backup

В результате в каталоге /docker/data/backup будут созданы резервные копии базы данных и файлов.

Чтобы восстановить базу данных из резервной копии, выполните:

make DUMP="userside_2019-05-08_09-23-19.dump" dbrestore

Также вы можете использовать другие удобные вам приемы, используемые при резервном копировании и восстановлении базы данных при работе с Docker-контейнерами.

Чтобы восстановить файлы из резервной копии, выполните:

cd /docker/data/backup
tar -xjf userside_2019-05-08_09-23-19.tar.bz2 -C /docker/data/

Дополнительное конфигурирование

Вам может понадобиться более тонко настроить бандл. Например, изменить значения переменных php.ini или же провести настройку postgresql.

PHP

Случай с php.ini уже был показан выше. Строка, которую необходимо раскомментировать, а также файл шаблона php.ini-example уже содержатся в бандле в качестве примера. Просто скопируйте файл php.ini-example, расположенный в каталоге config бандла, с именем php.ini, внесите необходимые правки, раскомментируйте строку, подключающую этот файл в качестве volume в сервисе fpm файла docker-compose.yml и перезапустите бандл

cd config
cp php.ini-example php.ini
nano php.ini
nano docker-compose.yml
make stop
make up

PostgreSQL

Для более производительной работы сервера PostgreSQL требуется произвести его настройку в соответствии с техническими параметрами сервера - тюнинг. С методиками тюнинга можно ознакомиться по ссылкам [1] и [2]. Также есть специальные инструменты, помогающие сформировать конфигурацию сервера PostgreSQL в удобном интерактивном виде [3] и [4].

Конфигурационные файлы PostgreSql транслируются из докер-контейнера вместе с базой данных в каталог /docker/data/db. В нем вы найдете все необходимые конфигурационные файлы, включая файл pg_hba.conf для настройки разрешений. После внесения правок просто перезапустите бандл макросами stop и up:

make stop
make up

Несколько копий USERSIDE на одном сервере

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

Бандл - это набор связанных между собой docker-контейнеров, имеющих общую виртуальную локальную сеть.

Выше в инструкции по развертыванию был указан каталог, относительно которого выполняются все действия: /docker/userside - это хороший пример, если вы планируете использовать одну копию USERSIDE на сервере, что чаще всего именно так.

Но, если Вы планируете использовать несколько копий, то каждую из них Вам придется развернуть в разные каталоги. Например: /docker/userside_1, /docker/userside_2

Также Вам придется настроить какой нибудь реверсивный прокси сервер, чтобы иметь более удобный доступ к разным копиям, например, на основании имени сервера из URL.

Ниже приведена схема из двух бандлов с реверсивным прокси, создание и настройка которой будет рассмотрена далее.

Инициализация нескольких бандлов

Клонирование репозитория с бандлом вы будете выполнять следующим образом:

mkdir -p /docker && cd $_
git clone https://github.com/userside/userside-docker.git userside_1
git clone https://github.com/userside/userside-docker.git userside_2

Если какой-то из бандлов должен работать на версии, отличной от текущей, то перейдите в каталог с этим бандлом и явно переключите ветку. Например, бандл userside_2 должен работать с версией USERSIDE 3.12

cd /docker/userside_2 && git checkout v3.12

Затем вам в каждом каталоге нужно будет выполнить команду инициализации

cd /docker/userside_1 && ./init.sh
cd /docker/userside_2 && ./init.sh

Изменение конфигурации бандлов

Имя бандла

Теперь, так как бандлов несколько, необходимо каждому назначить свое уникальное имя, чтобы они различались инструментом docker-compose, а также чтобы для каждого из них был создан соответствующий планировщик cron. Имена могут быть любыми, но они не должны содержать пробелов и других специальных символов. Используйте только символы латинского алфавита, цифры и знак подчеркивания. По умолчанию имя бандла userside, но в двух разных бандлах оно обязательно должно отличаться. Отредактируйте файл .env в обоих каталогах, изменив значение переменных PROJECT_NAME на userside_1 и userside_2 соответственно.

Абсолютные пути для монтируемых каталогов

Далее для каждого бандла необходимо прописать абсолютные пути в файле .env. За это отвечает переменная USERSIDE_BASE_DIR. Её значением должен быть абсолютный путь к бандлу.

Настройки внутренней сети

Теперь необходимо изменить настройки внутренней сети в бандлах. Внутри каждого docker-compose.yml в блоке networks указана подсеть, назначенная бандлу.

Нужно, чтобы эти подсети были разными и не пересекались. Количество хостов в подсети зависит от количества планируемых к запуску контейнеров с микросервисами. Подсеть должна однозначно умещать с запасом все контейнеры, которые будут созданы для бандла.

Настройка внешней сети и nginx

Во "внешний мир" транслирован только один TCP-порт № 80 контейнера nginx. По умолчанию, он транслируется в 80й порт и принимает соединение на всех внешних интерфейсах. Это указано в docker-compose.yml в настройке ports сервиса nginx и выглядит следующим образом:

- "80:80"

Теперь, так как бандлов несколько, то номер внешнего порта, в который транслируется каждый из 80х портов, должен отличаться. Если назначить контейнеру из первого бандла порт 80, а контейнеру из второго бандла порт 81, то заходить браузером на такие адреса будет неудобно - придется добавлять номер порта. Поэтому предлагается следующее решение.

Вместо портов 80, 81... предлагается использовать общий порт 80, но с различным адресом интерфейса, на который транслируется порт. Например, два бандла используют подсети 172.31.254.0/25 и 172.31.254.128/25 соответственно. Тогда можно изменить для каждого из них трансляцию портов следующим образом:

sed -i 's@- "80:80"@- "172.31.254.1:80:80"@' /docker/userside_1/docker-compose.yml
sed -i 's@- "80:80"@- "172.31.254.129:80:80"@' /docker/userside_2/docker-compose.yml

Далее установим и настроим реверсивный прокси-сервер, который будет принимать http-запросы из сети и транслировать их нужному контейнеру nginx.

Для этого необходимо установить nginx на локальный сервер (конечно, можно и используя Docker, по желанию, а можно и не nginx, а специализированные Docker-образы, но мы рассмотрим самый простой вариант - локальный nginx) и настроить в нем реверсивное проксирование. Локальный сервер будет принимать соединение на порту 80 (или 443) на всех интерфейсах (или на каких вам нужно) и, в зависимости от запрашиваемого доменного имени, проксировать соединение на http://172.31.254.1:80 и http://172.31.254.129:80, смотря, какому бандлу соответствует доменное имя.

sudo apt install nginx

Самый простой способ - изменить файл конфигурации /etc/nginx/conf.d/default.conf, приведя его к виду:

server {
    listen 80;
    server_name userside-1.company.net;
    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://172.31.254.1:80;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
    }
}

server {
    listen 80;
    server_name userside-2.company.net;
    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_pass http://172.31.254.129:80;
        proxy_send_timeout 240;
        proxy_read_timeout 240;
    }
}

В данном примере, в зависимости от имени сервера в http-запросе, будет выполнено проксирование на один из двух контейнеров nginx. Если пользователь открывает в браузере http://userside-1.company.net/oper/, то вызов будет передан контейнеру nginx первого бандла, а если http://userside-2.company.net/oper/ то контейнеру nginx второго бандла.

Конечно же, вместо HTTP вы можете использовать HTTPS SSL конфигурацию здесь с указанием сертификатов и т.д. Также здесь можно ограничить доступ, либо явно указав nginx, на каком интерфейсе нужно принимать подключения, либо при помощи директив управления доступом. Это уже лежит за рамками данного руководства, обращайтесь к официальной документации nginx для получения более подробной информации.

Теперь нужно проверить правильность конфигурации nginx и дать команду серверу перечитать конфигурацию:

sudo nginx -t && sudo nginx -s reload

Запуск

Теперь можно выполнить команду make install в каждом из бандлов. При этом будут созданы абсолютно независимые два бандла со своими версиями. Внутри каждого бандла будет работать свой набор контейнеров, никак не связанных с контейнерами из других бандлов.

Во время проверки URL адреса указывайте обязательно рабочий адрес вроде http://userside-1.company.net - таким образом Вы проверите правильность настройки.

Предложения по доработке бандла

Мы принимаем предложения по доработке бандла окружения следующими способами:

В виде issue в репозитории бандла на Github
В виде нормально оформленных pull-request'ов на Github
В виде предложений и замечаний через тикет-систему в личном кабинете.