Docker окружение: различия между версиями

Материал из WiKi - UserSide
Нет описания правки
Строка 8: Строка 8:


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


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


Мы рекомендуем использовать Docker только в том случае, если вы хорошо знаете и понимаете, как это работает. Мы не можем оказывать техническую поддержку по Docker, так как просто не располагаем специалистами команды поддержки, способными решать любые задачи на эту тему. Пожалуйста, если вы не знакомы с Docker, наверное вам не следует использовать этот способ установки.
В пределах этой инструкции используется понятие «версия 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, Вы найдете на официальном сайте: [https://docs.docker.com/install/ Docker CE], [https://docs.docker.com/compose/install/ Docker-compose].
Необходимо, чтобы на вашем сервере был установлен Docker CE, а также Docker compose. Для этого у Вас должен быть сервер под управлением 64-разрядной ОС Linux. Инструкции по установке Docker CE и Docker compose, в зависимости от дистрибутива и версии Linux, Вы найдете на официальном сайте: [https://docs.docker.com/install/ Docker CE], [https://docs.docker.com/compose/install/ Docker-compose].


Мы рекомендуем использовать GIT-репозиторий для получения новых версий бандлов. Для этого необходимо установить систему управлениями версиями GIT. Однако, если Вы по каким-то причинам предпочитаете не использовать репозиторий, Вы можете просто загружать архивы с наборами файлов (бандл) вручную, как будет сказано ниче.
Мы рекомендуем использовать GIT-репозиторий для получения новых версий бандлов. Для этого необходимо установить систему управлениями версиями GIT. Однако, если Вы по каким-то причинам предпочитаете не использовать репозиторий, Вы можете просто загружать архивы с наборами файлов (бандл) вручную, как будет сказано ниче.
= Версионирование бандла =
С 8 мая 2019 г. структура бандла целиком изменена для удобного версионирования и простой миграции на новые версии. Если вы разворачивали бандл до 8 мая 2019 то обязательно изучите раздел Обновление - Обновление со старой версии 3.12.
После 8 мая 2019 г. для версии USERSIDE 3.12 был создан новый бандл с новыми образами, а также был создан бандл для версии USERSIDE 3.13, релиз которого запланирован на середину мая 2019 г.
Под каждую версию USERSIDE существует своя специальная версия бандла. Каждая такая версия расположена в отдельной ветке в git-репозитории. Ветки имеют одноименное с версией USERSIDE наименование. Например, v3.12, v3.13 и т.д.
Самая новая версия бандла, соответствующая последней версии стабильного релиза USERSIDE, всегда отображается в основную ветку '''master'''.
Вы можете использовать ветку master всегда, если желаете обновляться на новые релизы USERSIDE с их выходом. В противном случае вы можете использовать ветку с конкретной версией бандла, соответствующей необходимой вам версии USERSIDE.


= Установка =
= Установка =
В данном разделе рассматривается установка и запуск бандла с нуля. Если Вы обновляетесь с 3.12, то вам также придется установить бандл для 3.13 с нуля, предварительно сделав все резервные копии. Это описано в разделе '''Обновление'''.
Все инструкции по установке содержатся в репозитории по адресу https://github.com/userside/userside-docker


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


Далее будут описаны шаги с указанием в качестве примера установку в каталог /docker/userside. Вы можете использовать любой удобный Вам путь расположения файлов, однако учитывайте то, что все примеры использования будут показаны именно для этого каталога.
= Эксплуатация =
 
Большинство часто используемых команд сформированы в короткие команды (макросы), выполнить которые можно используя вызов
== Клонирование репозитория ==
  sudo make <имя_команды>
Создайте каталог, в котором будет размещаться ваш бандл, а также в нем будет размещаться и всё окружение, включая файлы системы USERSIDE, резервные копии и файлы базы данных. И перейдите в него.
mkdir -p /docker && cd $_
Выполните команду клонирования репозитория в подкаталог с именем userside.
git clone https://github.com/userside/userside-docker.git userside
cd userside
Если вы желаете ограничиться конкретной веткой, чтобы все обновления файлов шаблонов не выходили за пределы этой ветки, вы можете перейти в нее, например, для версии 3.13 используйте ветку v3.13. Этот шаг является необязательным. Мы рекомендуем оставаться на ветке master.
git checkout v3.13
Для последующих обновлений файлов шаблонов вам достаточно выполнить команду:
git pull
 
== Без использования репозитория ==
Если по какой-то причине использование репозитория Вам не подходит, Вы можете загрузить файлы заготовок бандла вручную в виде архивов
 
[https://github.com/userside/userside-docker/releases Загрузить архивы бандлов]
 
Обратите также внимание на то, что для обновления бандла, вместо выполнения команды git pull из инструкций по обновлению ниже, вам каждый раз нужно будет загружать архив с новой версией бандла самостоятельно!
 
Создайте каталог, где будет размещаться бандл USERSIDE. Затем загрузите в него архив с бандлом, разархивируйте его и скопируйте файлы в подкаталог userside. Затем перейдите в него


mkdir /docker && cd $_ && mkdir -p userside
== Список команд ==
wget https://github.com/userside/userside-docker/archive/v3.13.0.tar.gz
tar xzf v3.13.0.tar.gz
rm v3.13.0.tar.gz
cp -fr userside-docker-3.13.0/* userside/
rm -rf userside-docker-3.13.0
cd userside
 
== Конфигурирвание бандла ==
Выполните команду инициализации - она скопирует все необходимые файлы из шаблонов, если те еще не существуют.
./init.sh
В результате у вас появятся файлы Makefile (содержит макросы для простого управления бандлом) и docker-compose.yml (содержит всю конфигурацию бандла).
 
=== docker-compose.yml ===
Вы должны отредактировать файл docker-compose.yml в соответствии с вашими требованиями.
 
==== servces ====
В разделе services находятся настройки всех сервисов, образующих бандл - окружение для работы USERSIDE. Далее описаны рекомендации по настройке сервисов.
===== postgres =====
Раздел environment:
* LANG - настройки языка, расположения и кодировки в формате LOCALE.
* TZ - часовой пояс.
* POSTGRES_DB - наименование базы данных (желательно оставить как есть).
* POSTGRES_USER - имя пользователя для доступа к БД.
* POSTGRES_PASSWORD - пароль для доступа к БД.
===== fpm =====
Раздел environment:
* TZ - часовой пояс
Раздел volumes:
* Также, если вам необходимо внести какие-либо настройки в php-ini, вы можете раскомментировать строку с подключением файла php.ini в качестве volume, затем вручную скопировать файл php.ini-example, находящийся в подкаталоге config, в файл с именем php.ini и внести в него необходимые правки.
===== nginx =====
Раздел ports:
* Укажите номер порта хоста (слева), который бы вы хотели транслировать на порт 80 контейнера nginx. Если на хосте у вас установлен сервер nginx и вы желаете проксировать http-запросы внутрь контейнера, то в этом случае желательно ограничить доступ к контейнеру по http, а также изменить порт хоста. Например, чтобы транслировать порт 8080 локального хоста на порт 80 контейнера, укажите "8080:80". Если необходимо ограничить доступ только с локального хоста (если используете проксирование), укажите "127.0.0.1:8080:80".
Раздел logging:
* Здесь вы можете настроить логгирование стандартными средствами docker. По умолчанию в шаблоне настроена ротация логов с максимальным размером файлов 20 Мб и их количеством 10 шт.
===== redis =====
Для использования пароля, раскомментируйте строку:
# command: redis-server --requirepass MYPASSWORDHERE
И замените MYPASSWORDHERE на длинную сложную парольную строку, которую можно получить путем любым из описанных далее способов:
echo "my-hard-password-here" | sha256sum
echo "my-hard-password-here" | sha1sum
pwgen -s 32 1
 
==== volumes ====
Здесь настраиваются пути к отображаемым внутрь контейнеров volumes. Желательно не изменять эти настройки без необходимости. Если же все таки есть необходимость их изменить, то также измените соответствующие пути и в Makefile
 
==== networks ====
Если указанная по умолчанию подсеть для бандла пересекается с какой либо вашей подсетью, измените ее здесь в значении параметра subnet. Также это может быть полезно, если вы поднимаете несколько бандлов для разных копий USERSIDE.
 
=== Makefile ===
Этот файл содержит макрокоманды, упрощающие управление бандлом. По сути, это всего лишь сокращения длинных команд, которые Вы также можете использовать для конкретизации параметров.
 
Главные макрокоманды вынесены в самый верх файла. Это те команды, которые могут пригодиться вам для работы с бандлом чаще остальных. Чаще всего, это просто более короткие псевдонимы других команд.
Чтобы выполнить любую из команд, достаточно указать ее после make в командной строке. При этом текущий каталог должен быть /docker/userside. Например, чтобы проинсталлировать бандл, выполните:
make install
 
==== Список команд ====
* '''up''' - запускает бандл
* '''up''' - запускает бандл
* '''down''' (или '''stop''') - останавливает бандл
* '''down''' (или '''stop''') - останавливает бандл
Строка 122: Строка 39:
* '''log''' - команда, отображающая все логи бандла в реальном времени (выход ctrl+c)
* '''log''' - команда, отображающая все логи бандла в реальном времени (выход ctrl+c)


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


Если вам необходимо изменить или дополнить список макросов, вы можете изменять этот файл так, как вам необходимо. При обновлении бандла обновится лишь шаблон этого файла, а не сам файл.
Если вам необходимо изменить или дополнить список макросов, вы можете изменять этот файл так, как вам необходимо. При обновлении бандла обновится лишь шаблон этого файла, а не сам файл.
== Инсталляция ==
При первом запуске необходимо выполнить макрос install:
make install
Этот макрос создаст необходимые каталоги, затем запустит бандл (при первоначальном запуске будут загружены все необходимые образы), затем запустит установщик userside, установит crontab для периодических операций и выполнит первоначальный запуск crontab для userside.
При установке обратите внимание на имена хостов для postgresql и redis. Именами хостов этих служб являются имена сервисов: postgres и redis соответственно.
После успешной инсталляции никаких дополнительных действий не требуется. Откройте в браузере адрес с установленным userside.
== Видеоинструкция ==
По ссылке https://youtu.be/9S3LsXvIulc находится видеоинструкция установки USERSIDE с использованием Docker-окружения.
В данной видеоинструкции используется домен docker.userside.demo, А-запись которого соответствует IP-адресу сервера, на котором производится установка.
= Эксплуатация =
При необходимости бандл можно остановить командой
make stop
И запустить командой
make up
Следить за логами в реальном времени командой
make log
Запустить консоль PostgreSQL psql
make postgres-psql
Запустить консоль Redis redis-cli
make redis-cli
Запустить планировщик userside вручную
make cron-run
Очистить кэш (Redis)
make flush
Также можно использовать команду docker-compose для случаев, не предусмотренных набором макросов (можете дополнить список макросов самостоятельно).
docker-compose -p userside ps
Приведенная выше команда отобразит все контейнеры бандла и их состояние.


= Резервное копирование и восстановление =
= Резервное копирование и восстановление =
Во время инсталляции создается crontab в /etc/cron.d/userside, в котором прописаны три действия: периодический запуск планировщика userside и два действия для резервного копирования базы данных и файлов.


Если Вам необходимо вручную создать резервные копии базы данных и файлов, Вы можете запустить макрос:
Если Вам необходимо вручную создать резервные копии базы данных и файлов, Вы можете запустить макрос:
Строка 192: Строка 75:
  make stop
  make stop
  make up
  make up
= Обновление =
Мы рекомендуем производить обновление в то время, когда приостановка работы системы не влияет на работу компании. Во время обновления могут произойти нештатные ситуации, от которых никто не застрахован. И, хотя у нас этот процесс отлажен достаточно четко, все равно, пожалуйста, не полагайтесь на волю случая.
'''Не забывайте делать резервное копирование файлов USERSIDE, базы данных, а также файлов docker-compose.yml и Makefile перед обновлением!'''
== В пределах минорной версии ==
Если вы обновляетесь в пределах минорной версии. Например, в пределах 3.13 (с 3.13.2 на 3.13.8), то вам достаточно воспользоваться макросом update:
git pull
make update
В этом случае автоматически будет выполнено резервное копирование базы данных и файлов, обновление docker-образов и запуск инсталлятора для произведения обновления самого приложения.
Как правило, в пределах минорной версии никаких изменений в окружении не происходит (если того не требуют исправления, о чем всегда будет указано в changelog к версии, на которую вы планируете обновиться), поэтому больше никаких действий не требуется.
== На новую минорную версию ==
Если вы обновляетесь на новую минорную версию. Например, с версии 3.13.87 на версию 3.14.2, то обновление в полностью автоматическом режиме не подойдет. Эта инструкция также справедлива и для обновления с версии 3.12 на новую минорную версию (например, 3.13), при условии, что бандл для 3.12 вы разворачивали по инструкции после 8 мая 2019 г. Для этого необходимо сначала обязательно ознакомиться с информацией по обновлению на новую минорную версию, затем проделать следующие шаги:
make backup
make stop
git pull
Затем '''внимательно''' просмотреть файлы docker-compose.yml-example и Makefile-example на предмет новых сервисов, томов, зависимостей, наименований образов, макросов. Затем дополнить свои файлы docker-compose.yml и Makefile недостающими или измененными строками. Затем выполнить:
make bundle-pull
make up
make postgres-postgis-update
make userside-install
После установки убедиться, что все работает корректно.
== Обновление с устаревшей версии 3.12 на новую ==
Если Вы разворачивали Docker-окружение для версии 3.12 по инструкции до 8 мая 2019 года, то вам необходимо проделать последовательность действий, описанную в этом разделе.
Как убедиться в том, что вы разворачивали Docker-окружение, которое является устаревшим? Если у вас каталог с бандлом (по инструкции это был каталог ~/userside-docker) и каталог с устанавливаемым приложением и резервными копиями (по инструкции это были каталоги /opt/userside /opt/backup), то ваша версия устарела. В новой версии бандла v3.12 организация каталогов точно такая же, как и в v3.13 и во всех будущих версиях.
Итак, если у вас именно устаревший бандл, то проделайте следующее:
=== Резервное копирование ===
Перейдите в каталог с бандлом (~/userside-docker если вы следовали инструкции и не меняли его месторасположение) и выполните резервное копирование, запустив команду
make backup
Далее создайте где-то в надежном месте каталог, в котором будут размещены промежуточные резервные копии. Например, пусть это будет /backup и скопируйте в него все файлы резервных копий, а также файл docker-compose.yml
mkdir /backup
sudo cp /opt/backup/* /backup
cp docker-compose.yml /backup
Убедитесь в том, что файлы резервных копий скопированы!
=== Удаление старых файлов ===
Остановите работу бандла и удалите его
docker-compose -p userside down -v
Теперь удалите каталог с бандлом, каталог с приложением и бекапами
make uninstall
cd /
sudo rm -rf ~/userside-docker
sudo rm -rf /opt/userside /opt/backup
На данный момент у вас должны остаться только резервные копии.
=== Установка нового бандла ===
Теперь произведите установку бандла с самого начала. Вы можете использовать ветку master (она содержит актуальную версию 3.13 или ту версию, которая будет актуальна на момент чтения этих строк) или же выбрать другую ветку, как показано выше в разделе установки. Мы рекомендуем использовать ветку master. Выполните следующие команды:
mkdir -p /docker && cd $_
git clone https://github.com/userside/userside-docker.git userside
cd userside
Теперь выполните инициализацию - в результате в каталоге появятся файлы docker-compose.yml и Makefile. Отредактируйте файл docker-compose.yml, указав в нем настройки для сервисов postgres и nginx точно такие же, как были в старом файле docker-compose.yml (который Вы сохранили в /backup)
./init.sh
nano docker-compose.yml
Создайте необходимые каталоги, запустите бандл и проверьте его работу. Статус всех контейнеров должен быть '''Up'''
make create-env-dir
make up
docker-compose -p userside ps
=== Восстановление из резервной копии ===
Восстановите базу данных и файлы из резервной копии. Для этого скопируйте файлы последней резервной копией, которая была сделана непосредственно перед обновлением, из каталога /backup в каталог /docker/userside/data/backup (имена файлов у вас будут другие!), выполните команды восстановления и команду обновления postgis для базы данных. (В процессе восстановления могут быть ошибки записи для расширения postgis - это нормально, так как у пользователя базы данных userside недостаточно для этого прав)
cp /backup/userside_2019_05-07* data/backup/
make DUMP="userside_2019-05-07_00-00-00.dump" dbrestore
tar -xjf data/backup/userside_2019-05-07_16-49-41.tar.bz2 -C /docker/userside/data/
make postgres-postgis-update
=== Запуск обновления ===
Теперь необходимо запустить скрипт-инсталлятор для обновления версии
make userside-install
Во время обновления вам понадобится ввести параметры подключения к сервисам, которых еще не существовало в версии 3.12. Для подключения к сервису Redis используйте имя хоста redis, остальные параметры оставьте по умолчанию.
После обновления выполните команду установки crontab
make cron-setup
Убедитесь, что USERSIDE работает нормально.
На этом обновление с версии 3.12 можно считать завершенным.


= Несколько копий USERSIDE на одном сервере =
= Несколько копий USERSIDE на одном сервере =
Строка 301: Строка 103:


  cd /docker/userside_2 && git checkout v3.12
  cd /docker/userside_2 && git checkout v3.12
На данный момент существует две ветки - v3.13 - она же текущая ветка (master), которая подходит для USERSIDE 3.13 и новее и ветка v3.12, которая подходит для USERSIDE 3.12. Если Вы эксплуатируете USERSIDE 3.13 и новее, то ни на какую ветку переключаться дополнительно не нужно. Разве что можно явно переключиться на v3.13, чтобы при появлении более новых веток (например, v3.15) навсегда остаться именно на v3.13.


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


== Изменение конфигурации бандлов ==
== Изменение конфигурации бандлов ==
Внесите необходимые изменения в файлы docker-compose.yml, как указано выше [[Docker_окружение#docker-compose.yml|в разделе про конфигурирование docker-compose.yml]]


=== Имя бандла ===
=== Имя бандла ===


Теперь, так как бандлов несколько, необходимо каждому назначить свое уникальное имя, чтобы они различались инструментом docker-compose, а также чтобы для каждого из них был создан соответствующий планировщик cron. Имена могут быть любыми, но они не должны содержать пробелов и других специальных символов. Используйте только символы латинского алфавита, цифры и знак подчеркивания. По умолчанию имя бандла ''userside'', но в двух разных бандлах оно обязательно должно отличаться. Отредактируйте файл '''Makefile''' в обоих каталогах, изменив значение переменной <code>PROJECT_NAME</code> на ''userside_1'' и ''userside_2'' соответственно, либо воспользуйтесь командами, чтобы сделать это автоматически:
Теперь, так как бандлов несколько, необходимо каждому назначить свое уникальное имя, чтобы они различались инструментом docker-compose, а также чтобы для каждого из них был создан соответствующий планировщик cron. Имена могут быть любыми, но они не должны содержать пробелов и других специальных символов. Используйте только символы латинского алфавита, цифры и знак подчеркивания. По умолчанию имя бандла ''userside'', но в двух разных бандлах оно обязательно должно отличаться. Отредактируйте файл '''.env''' в обоих каталогах, изменив значение переменных <code>PROJECT_NAME</code> на ''userside_1'' и ''userside_2'' соответственно.
 
sed -i "s/^PROJECT_NAME.*/PROJECT_NAME=userside_1/" /docker/userside_1/Makefile
sed -i "s/^PROJECT_NAME.*/PROJECT_NAME=userside_2/" /docker/userside_2/Makefile


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


Далее для каждого бандла необходимо прописать абсолютные пути в файлах docker-compose.yml в разделе volumes:
Далее для каждого бандла необходимо прописать абсолютные пути в файле '''.env'''. За это отвечает переменная <code>USERSIDE_BASE_DIR</code>. Её значением должен быть абсолютный путь к бандлу.
 
sed -i "s@/docker/userside/data/@/docker/userside_1/data/@" /docker/userside_1/docker-compose.yml
sed -i "s@/docker/userside/data/@/docker/userside_2/data/@" /docker/userside_1/docker-compose.yml


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


Теперь необходимо изменить настройки внутренней сети в бандлах. Внутри каждого docker-compose.yml в блоке ''networks'' указана подсеть, назначенная бандлу.
Теперь необходимо изменить настройки внутренней сети в бандлах. Внутри каждого docker-compose.yml в блоке ''networks'' указана подсеть, назначенная бандлу.
Можно поступить двумя способами на выбор:
# Для каждого бандла прописать свою подсеть (достаточно /28), чтобы они не пересекались с подсетями, используемыми в вашей сети (ваше оборудование или абоненты). Например, для ''userside_1'' можно оставить 172.31.255.0/28, а для ''userside_2'' укажите следующий блок: 172.31.255.16/28
# Удалить вообще блок ''networks'', а также удалить в каждом из сервисов, описанных в этом файле, блок ''networks'' - тогда подсети будут назначены бандлам автоматически из стандартной подсети docker (обычно это 172.17.0.1/16, но её "можно изменить":https://docs.docker.com/v17.09/engine/userguide/networking/default_network/custom-docker0/). Однако, мы не рекомендуем использовать такой способ, хоть он и проще, а рекомендуем явно назначить подсети размера /28 каждому бандлу вручную!
Для первого вашего бандла подсеть можно оставить такой как есть, если она вас устраивает. Но для следующего бандла она должна быть другой. Измените ее в docker-complose.yml в разделе ''networks'':


sed -i "s@172\.31\.255\.0@172.31.255.16@" /docker/userside_2/docker-compose.yml
Нужно, чтобы эти подсети были разными и не пересекались. Количество хостов в подсети зависит от количества планируемых к запуску контейнеров с микросервисами. Подсеть должна однозначно умещать с запасом все контейнеры, которые будут созданы для бандла.


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


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


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


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


Для этого необходимо установить nginx на локальный сервер (''конечно, можно и используя Docker, по желанию, а можно и не nginx, а специализированные Docker-образы, но мы рассмотрим самый простой вариант - локальный nginx'') и настроить в нем [https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/ '''реверсивное проксирование''']. Локальный сервер будет принимать соединение на порту 80 (или 443) на всех интерфейсах (или на каких вам нужно) и, в зависимости от запрашиваемого доменного имени, проксировать соединение на порт 127.0.0.1:8081 или 127.0.0.1:8082, смотря, какому бандлу соответствует доменное имя.
Для этого необходимо установить nginx на локальный сервер (''конечно, можно и используя Docker, по желанию, а можно и не nginx, а специализированные Docker-образы, но мы рассмотрим самый простой вариант - локальный nginx'') и настроить в нем [https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/ '''реверсивное проксирование''']. Локальный сервер будет принимать соединение на порту 80 (или 443) на всех интерфейсах (или на каких вам нужно) и, в зависимости от запрашиваемого доменного имени, проксировать соединение на http://172.31.254.1:80 и http://172.31.254.129:80, смотря, какому бандлу соответствует доменное имя.


  sudo apt install nginx
  sudo apt install nginx
Строка 365: Строка 151:
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_pass http://127.0.0.1:8081;
         proxy_pass http://172.31.254.1:80;
         proxy_send_timeout 240;
         proxy_send_timeout 240;
         proxy_read_timeout 240;
         proxy_read_timeout 240;
Строка 378: Строка 164:
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_pass http://127.0.0.1:8082;
         proxy_pass http://172.31.254.129:80;
         proxy_send_timeout 240;
         proxy_send_timeout 240;
         proxy_read_timeout 240;
         proxy_read_timeout 240;
Строка 384: Строка 170:
  }
  }


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


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

Версия от 14:13, 26 января 2022

ВНИМАНИЕ!

Если вы уже используете 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
  • В виде предложений и замечаний через тикет-систему в личном кабинете.