Установка с использованием Docker
Начиная с версии ERP USERSIDE 3.12 поддерживается развёртывание системы внутри окружения, построенного с использованием Docker-контейнеров.
Соглашение
Данная инструкция предназначена для системных администраторов, знакомых с виртуальной средой Docker. Данная инструкция предполагает установку на хост с операционной системой Linux. Данная инструкция не содержит материалов, объясняющих работу виртуальной среды Docker, а также ее обслуживания и администрирования. Ответы на вопросы касательно работы, обслуживания и администрирования Docker необходимо искать в официальной документации. Зона ответственности службы технической поддержки USERSIDE не распространяется на темы, связанные с Docker. Просьба отнестись с пониманием.
Описание
Данная инструкция описывает процесс установки окружения, необходимого для работы системы ERP USERSIDE. Окружение состоит из трех контейнеров, каждый из которых обеспечивает работу своей службы: nginx, php-fpm, postgresql. Образы, на базе которых строятся контейнеры, включают все необходимые компоненты и настройки, необходимые для полноценного функционирования системы USERSIDE. Образы не включают программный код системы USERSIDE и поэтому являются публичными. Сама система USERSIDE устанавливается на том, подключенный к контейнеру, утилитой-установщиком. Все эти процессы автоматизированы.
Требования
Загрузка набора файлов для развёртывания стека
До недавнего времени использовался один единственный набор файлов, при помощи которого можно было развернуть стек с окружением для работы USERSIDE 3.11 и 3.12. Для новых версий USERSIDE, начиная с 3.13 и новее будут существовать несколько наборов, каждый для своей версии или группы версией.
Наборы файлов для развертывания находятся в публичном GIT-репозитории. Главная ветка master содержит основной на данный момент набор файлов, которые предназначены для развёртывания стека для версий USERSIDE 3.11 и 3.12. Все остальные наборы будут расположены в отдельных ветках по номеру версии. Например, новый набор для версии 3.13 расположен в ветке v3.13. Ветка master всегда будет содержать набор для последнего продуктивного стабильного релиза USERSIDE. На данный момент им является 3.12. После выхода первого стабильного релиза версии 3.13, ветка master будет указывать на ветку v3.13, но ветка v3.12 также будет доступна, но уже не будет указывать на master. Начиная с версии 3.13 вы можете всегда использовать ветку master, так как изменения, внесенные в наборы файлов, начиная с версии 3.13, не будут деструктивными.
В текущем наборе файлов для версии 3.11 и 3.12 (из ветки master) имеются некоторые ошибки, из-за которых невозможно просто обновиться на версию 3.13. Главная ошибка заключается в том, что репозиторий содержит файлы Makefile и docker-compose.yml, а не их шаблоны и при обновлении файлов из репозитория эти файлы будут заменены файлами репозитория, что недопустимо.
Очень важно! Если вы обновляетесь с 3.12 на 3.13 или более новые версии, обязательно следуйте инструкциям в разделе Обновление!
Далее указываются способы для установки стека userside разных версий.
Основной способ (для 3.11 и 3.12)
cd ~ git clone https://github.com/userside/userside-docker.git cd userside-docker
Чтобы обновить набор файлов, выполните:
git pull
Способ для версии 3.13 и новее
Внимание! Если Вы производите обновление с предыщущих версий (3.11, 3.12), то обязательно обратитесь к разделу Обновление!
mkdir /docker git clone https://github.com/userside/userside-docker.git userside cd userside
Далее необходимо переключиться на необходимую ветку, например, для версии 3.13 ветка называется v3.13.
git checkout v3.13
После чего выполнить создание новых наборов файлов конфигурации стека
./init.sh
После этих действий в каталоге появятся файлы Makefile и docker-compose.yml. Отредактируйте docker-compose.yml при необходимости (имя пользователя, пароль для БД, порт для WEB-сервер и т.д.). В последствии при обновлениях репозитория эти файлы не будут затронуты! (Это основное отличие от ветки v3.12, где репозиторий содержал не примеры этих файлов, а сами эти файлы).
Установка
Далее все команды должны выполняться в каталоге с набором файлов.
Конфигурация стэка
Первое, что вам необходимо сделать, - настроить стэк docker-compose. Для этого необходимо отредактировать файл:
nano docker-compose.yml
Следует обратить внимание на:
- Переменные окружения, расположенные в блоках environment: внутри блоков, расположенных в блоке services:. Они определяют основные настройки системы. Вы должны правильно указать ваш часовой пояс (TZ), настройки базы данных PostgreSQL (POSTGRES_*).
- Номер порта в службе nginx: (параметр ports:) слева от двоеточия - порт локального хоста, который необходимо транслировать в порт 80 (справа от двоеточия) внутри контейнера nginx. Если на вашем хосте используется WEB-сервер для работы других приложений, вам необходимо изменить трансляцию портов таким образом, чтобы порты веб-сервера хоста и транслируемого из контейнера не пересекались, а в самом WEB-сервере хоста настроить проксирование на этот порт. Если же WEB-сервера на хосте нет, то ничего не нужно изменять.
- Тома (блок volumes: внизу конфига). Значением параметра device: здесь является каталог локального хоста. Этот каталог будет подключен как том в файловую систему контейнера. Рекомендуется оставить значение по умолчанию. Единственное, что может быть полезно - изменить место хранение бекапов (каталог должен существовать на хосте). Кроме простого изменения каталога для бекапов Вы также можете изменить и драйвер для этого тома, например, использовав один из сетевых драйверов, позволяющих подмонтировать сетевой том в файловую систему контейнера. Это позволит хранить бекапы на другом хосте, что является более безопасным.
- Сети (блок networks: внизу конфига). Если подсеть, указанная в параметре subnet:, пересекается с подсетями, которые вы используете, то вы можете изменить ее на любую другую с маской не менее /29, однако рекомендуется использовать маску подсети не уже /28.
Сохраните файл после редактирования.
После того, как конфигурация выполнена, необходимо создать каталоги для монтирования томов. Если вы оставили каталоги, указанные в конфиге по умолчанию, то просто выполните:
sudo mkdir -p /opt/userside /opt/backup
Запуск набора установки
Находясь в каталоге с набором файлов, выполните:
sudo make install
Это запустит процесс загрузки Docker-образов, создания контейнеров на основании информации из docker-compose.yml, после чего запустит утилиту-инсталлятор USERSIDE, а затем запустит процесс создания конфигурации для cron и logrotate.
Во время работы утилиты-инсталлятора USERSIDE, вам понадобится лицензионный ключ, который вы можете получить в личном кабинете.
В процессе установки Вам будет предложено установить приложение в каталог /app/userside. Соглашайтесь, так как именно такой каталог используется как точка монтирования внешнего тома внутри контейнера.
После выполнения команды вы получите целиком готовую к работе систему. Откройте в браузере адрес, введенный в утилите-инсталляторе для проверки и войдите, используя имя пользователя admin и пароль 1234.
В течение первой минуты Вы можете наблюдать сообщение о не работающем планировщике, но спустя минуту, после первого запуска, это сообщение исчезнет.
Резервное копирование
В ходе инсталляции в системный cron прописываются правила для выполнения резервного копирования. Резервное копирование файлов приложения выполняется в 3 часа и базы данных в 4 часа. Вы можете отредактировать время запуска на свое усмотрение:
nano /etc/cron.d/userside
По умолчанию файлы резервных копий находятся в каталоге /opt/backup хоста.
Чтобы запустить резервное копирование вручную, находясь в каталоге с набором файлов вполните:
sudo make backup
После этого проверьте факт создания файлов резервной копии в каталоге /opt/backup (если вы не изменили его в конфиге).
Восстановление
Для восстановления резервной копии файлов, просто разархивируйте файл архива резервной копии в каталог с ERP USERSIDE. Для этого лучше сначала остановить стэк окружения командой make stop, затем удалить каталог /opt/userside (если вы не изменяли его месторасположение) и извлечь каталог userside из архива командой:
sudo tar -xjf userside_2018-03-21_13-06-03.tar.bz2 -C /opt
Для восстановления резервной копии базы данных воспользуйтесь скриптом восстановления, передав ему в качестве параметра имя файла дампа базы, расположенного в каталоге с резервными копиями. Путь к каталогу указывать не нужно. Скрипт работает с каталогом резервных копий напрямую.
Находясь в каталоге с набором файлов, выполните:
sudo make DUMP="userside_2018-03-21_13-06-02.dump" dbrestore
Обслуживание
PostgreSQL
Если необходимо воспользоваться консольным клиентом psql, находясь в каталоге с набором файлов, выполните:
sudo make psql
Остановка и запуск контейнеров Docker
При необходимости остановить работу окружения, необходимого для работы системы USERSIDE, находясь в каталоге с набором файлов выполните:
sudo make stop
Если необходимо остановить и удалить контейнеры, а так же информацию о томах (сами каталоги на хосте не удаляются) и информацию о внутренней сети, выполните:
sudo make down
Будьте осторожны. Эта процедура удалит базу данных. Сделайте резервную копию данных перед ее выполнением.
Если необходимо снова запустить контейнеры (или создать их и запустить), выполните:
sudo make up
Обновление USERSIDE
Внимание! Перед обновлением обязательно сделайте резервную копию данных!
Находясь в каталоге с наборами файлов, выполните:
sudo make update
Также Вы можете выполнить и команду sudo make install. В этом случае будет произведена попытка создания контейнеров, запуска инсталлятора и конфигурирование cron и logrotate. Этот способ подойдет, если вы хотите начать сначала. Будьте осторожны, это действие может пересоздать том с базой данных. Обязательно сделайте резервную копию данных перед выполнением этой команды.
Ручной запуск CRON
Это может быть необходимо при диагностике проблем, связанных с периодическими задачами.
Для начала закомментируйте строку запуска планировщика в файле /etc/cron.d/userside
Затем, спустя минуту, находясь в каталоге с набором файлов, выполните:
sudo make run-cron
После того, как диагностика закончена, не забудьте раскомментировать планировщик в файле /etc/cron.d/userside
Удаление USERSIDE
Чтобы полностью переустановить стек, либо перенести систему на другой сервер, вам может понадобиться процедура удаления системы USERSIDE с хоста. Для этого, находясь в каталоге с набором файлов, сначала выполните команду резервного копирования данных, а затем команду удаления:
sudo make backup sudo make uninstall
Команда удаления остановит, а затем удалит контейнеры окружения USERSIDE, затем удалит все тома (в том числе том с базой данных), сетевые настройки, файлы логов nginx и файлы конфигурации cron и logrotate.
Содержимое каталогов резервных копий и самой системы USERSIDE не удаляется. Вы без труда сможете восстановить работу системы из резервных копий базы данных и файлов.
Восстановление после удаления
Есть необходимо восстановить работу системы USERSIDE из существующих резервных копий, то необходимо сделать следующее:
- Загрузите набор файлов
- Создайте каталог для резервных копий, например /opt/backup и поместите в него файлы резервных копий, из которых необходимо произвести восстановление. Должно быть два файла: файлы системы *.tar.bz2 и резервная копия базы данных *.dump
- Восстановите файлы командой
sudo tar -xjf имя_файла_резервной_копии.tar.bz2 -C /opt, если хотите, чтобы приложение размещалось в каталоге /opt/userside или же выберите другое расположение, если в этом есть необходимость. - Отредактируйте файл docker-compose.yml, указав в разделе volumes: расположение каталога для резервных копий и каталога с приложением, если вы их изменили.
- Находясь в каталоге с набором файлов, запустите процедуру создания и запуска контейнеров, выполнив
sudo make up. - Выполните восстановление резервной копии базы данных. Для этого находясь в каталоге с набором файлов, выполните
sudo make DUMP="имя_файла_резервной_копии.dump" dbrestore. - Запустите скрипт, создающий конфигурацию планировщика и ротацию логов: ./create-configs.sh
- Проверьте работу приложения
TL;DR
cd ~ git clone https://github.com/userside/userside-docker.git cd userside-docker sudo mkdir -p /opt/userside /opt/backup sudo make install