Инструкция по установке

В данном разделе описаны подготовка к запуску и запуск приложений с помощью docker-compose файла. Сервисы EnDocs запускаются с помощью docker-compose, автоматически выписываются сертификаты с помощью certbot и центра сертификации LetsEncrypt для указанных доменов. Дополнительно необходимо иметь настроенный сервер БД mySQL.

2.1 Требования к серверу

1. С установленной ОС Linux (рекомендуется Ubuntu 20.04 или выше)
2. С установленными пакетами docker, docker-compose
3. С выделенным статическим IP-адресом (необязательно, если используется собственный web-сервер/балансировщик и т.д.)
4. Должны быть созданы доменные адреса вида:
   1. <your-domain.com>
   2. <your-domain.com>
   3. <your-domain.com>
5. Созданы DNS A-записи для доменных адресов
6. Открыты входящие соединения по протоколу TCP на порты 80, 443

Так же возможен вариант использования отдельного веб-сервера и собственных SSL-сертификатов. Подробности в разделе Запуск приложений.

2.2 Подготовка проекта

Шаг 1. Создание пользователя и папок

Необходимо создать пользователя (далее, для примера, имя пользователя: app), от имени которого будет выполняться запуск. Добавить пользователя в группу docker.

В домашней папке пользователя /home/app разместить предоставленные папки endocs и images.

В папке endocs находится все необходимое для запуска приложений.

В папке images скрипт импорта docker-образов приложений unpack.sh, туда же необходимо скопировать предоставленный архив с образами (например: images-521c9131-2022-11-23_02-11-50.tar.gz).

Шаг 2. Импорт образов

Перейти в папку images
cd /home/app/images

Запустить скрипт импорта

./unpack.sh  images-521c9131-2022-11-23_02-11-50.tar.gz

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

endocs/api:521c9131

endocs/bs:521c9131

endocs/web:521c9131

endocs/apimobile:521c9131

Каждому образу будет проставлен «плавающий» тэг latest (рекомендуется не использовать для запуска тэг latest, а указывать конкретную версию, т.е. хэш коммита, так будет понимание какая именно версия приложений запущена. В данном примере это 521c9131).

Для дальнейшей настройки запоминаем список образов с тэгами.

Для просмотра всех docker-образов используем команду docker images.

Шаг 3.

Настройка переменных окружения и прочих настроек.

Переходим в папку endocs

cd /home/app/endocs

Редактируем файл .env:

1. COMPOSE_PROJECT_NAME задаем значение имени docker-compose проекта (можно оставить без изменений)
2. IMG_TAG указываем имя тэга образов (полученного на Шаге 2)
3. указываем имена образов для каждого сервиса (сверяемся с полученным на Шаге 2 списком)
4. SETTINGS_FILE указываем имя файла с настройками приложений

Пример файла .env:

Редактируем appsettings.json (в данном примере appsettings-demo.json)

Вносим необходимые правки, например connection string для подключения к mySql БД, адрес приложения:

“ConnectionStringMySql”: “server=XXXX;port=3306;database=XXXX;Uid=XXXX;Pwd=XXXX”

“HttpClient_Address”: “https://ecm.mydomain.com”

И прочие настройки приложений.

Редактируем config.env (пропустить, если используется собственный web-сервер и SSL-сертификаты)

Это файл с переменными окружения для certbot и nginx

Настраиваем значения переменных DOMAINS и CERTBOT_EMAILS.

Важно! Значение должно быть в кавычках! В переменной DOMAINS определяется список доменов разделенных пробелом; в переменной CERTBOT_EMAILS валидные e-mail адреса администратора доменов для каждого из них разделенные пробелом. Далее для примера будем использовать mydomain.com (вы должны использовать собственное имя домена!!!).

ВАЖНО! Значение переменной CERTBOT_TEST_CERT при первом запуске всегда устанавливаем = 1

Пример файла config.env:

Переименовываем файлы конфигураций nginx (пропустить, если используется собственный web-сервер и SSL-сертификаты)

В папке vhosts/ расположены конфигурации виртуальных хостов nginx. Имена файлов должны соответствовать именам доменов конкретных сервисов и иметь расширение .conf. Необходимо их переименовать в соответствии с вашими доменными именами! Содержимое менять не нужно.

Пример:

2.3 Запуск приложений

Первый (тестовый) запуск приложений.

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

Шаг 1.

Убедиться, что значение переменной `CERTBOT_TEST_CERT=1` в файле config.env

Шаг 2.

Создание docker-волюмов

cd /home/app/endocs

docker volume create –name=nginx_conf

docker volume create —name=letsencrypt_certs

Запуск docker-compose и вывод логов

docker compose up -d –build && docker compose logs -f

Прочитав логи убедиться, что приложения стартовали, и сертификаты выписались (Сертификаты должны выписаться, но браузеры не доверяют тестовым сертификатам. Если все домены доступны по https, приложения работают, можно выписывать сертификаты в нормальном режиме)

* в логах для каждого домена должны появиться сообщения:

Switching Nginx to use Let’s Encrypt certificate

Reloading Nginx configuration

Если все в норме, переключаемся на «продовые» сервера letsencrypt и выписываем “честные” сертификаты (Запуск в «боевом» режиме.)

2.4 Запуск в «продуктивном» режиме

Шаг 1.

Остановить docker-compose

docker compose down

Шаг 1.

Изменить значение переменной `CERTBOT_TEST_CERT=0` в файле config.env

Шаг 2.

Пересоздать docker-волюм с SSL-сертификатами

docker volume rm letsencrypt_certs

docker volume create –name=letsencrypt_certs

Шаг 3.

Запустить docker-compose и убедиться, что все в порядке.

docker compose up -d && docker compose logs -f

2.5 Вариант с использованием собственного web-сервера и SSL-сертификатов

Если у вас уже есть работающий web-сервер, подготовленные домены, можно использовать его.
Необходимо в файле docker-compose.yml закомментировать или удалить описание сервисов nginx, certbot, cron и описание docker-волюмов nginx_conf, letsencrypt_certs, certbot_acme_challenge. Добавить порты, которые будут открыты для подключения к сервисам.

Пример docker-compose.yml файла:

На своей стороне настроить соответствующим образом web-сервер, для примера смотреть папки nginx и vhosts.
Необходимо настроить proxy-pass с хостов на сервисы (в соответствии с примером выше):
1. ecm.mydomain.com — сервис web порт 8080

2. api.mydomain.com — сервис api порт 8081
3. mobile.mydomain.com — сервис apimobile порт 8082

Настроить фаерволлы в соответствии с вашей конфигурацией сети.

Запустить docker-compose:

cd /home/app/endocs

docker compose up -d

Проверить логи на наличие ошибок:

docker compose logs -f

2.6 Перезапуск сервисов с обновленными образами

Шаг 1.

Загружаем на сервер архив с новыми образами в папку /home/app/images

Распаковываем новые образы

cd /home/app/images

./unpack.sh  <имя нового архива с образами>.tar.gz

Записываем имя нового тэга и правим значение переменной IMG_TAG в /home/app/endocs/.env файле

Шаг 2.

Перезапускаем docker-compose

docker compose up -d

Шаг 3.

Убеждаемся, что контейнеры запустились из новых образов (проверяем тэг)

docker compose images

Шаг 4.

Смотрим логи и проверяем работоспособность

docker compose logs -f

2.7 Полезные команды

Все команды docker compose <command> выполняются только из папки, содержащей docker-compose.yml (в нашем примере /home/app/endocs/)

смотреть логи всех сервисов

docker compose logs -f

смотреть логи всех сервисов

docker compose logs -f <service_name>

просмотр сервисов и их образов

docker compose images

запуск сервисов в фоне

docker compose up -d

остановка сервисов

docker compose down

просмотр статуса запущенных контейнеров

docker ps

просмотр используемых ресурсов

docker stats

просмотр занимаемого docker места

docker system df