# Mini Apps со stage и prod, привязкой GitHub, БД и связкой Backend и Frontend, развернутых в разных проектах ## Развертывание Backend + Frontend + Database (PostgreSQL | SQLite) Для работы web приложения, состоящего из Backend, Frontend и базы данных, в Amvera вам нужно создать отдельные проекты для каждого из частей веб приложения и связать их по доменному имени. Причем, можно связать как по [внутреннему доменному имени](https://docs.amvera.ru/applications/configuration/network.html#id2), так и [внешнему](https://docs.amvera.ru/applications/configuration/network.html#id3). К примеру, можно отправлять запросы к Backend по конкретному созданному маршруту и внешнему доменному имени. Добавим маршрут hello с POST методом в Backend: ``` app.post('/hello', async (req, res) => { await SendAlertMessage(req.body); res.status(200).send(); }); ``` А в Frontend создадим запрос по внешней ссылке: ``` const fetchResponse = await fetch('https://backend-username.amvera.io/hello'); ``` ## Как привязать бесплатное доменное имя Amvera или свое из ЛК регистратора На примере MiniApp, свяжем бота и frontend по внешнему доменному имени с протоколом HTTPS. Telegram требует использование HTTPS протокола при привязке webApp к боту. Создадим домен: 1) Во вкладке "Настройки" ищем секцию с доменными именами и в правом верхнем углу жмем на кнопку "Добавить доменное имя". 2) В параметре "Тип подключения" выбираем `HTTPS`, а в "Типе домена" выбираем "Бесплатный домен Amvera", если не планируете привязать свой. В случае, если вы хотите привязать собственное доменное имя (на примере регистратора reg.ru), следуйте [этой инструкции](https://docs.amvera.ru/applications/configuration/network.html#id5). Подтверждаем и привязываем доменное имя. Нужно подождать около 2-х минут для полной привязки домена и выдачи сертификата. Получившийся адрес копируем и отправляем BotFather (или вставляем в коде как webApp) для привязки. ## Подключение БД (PostgreSQL или SQLite) ### PostgreSQL Подключить PostgreSQL вы можете также либо по внутреннему доменному имени, либо, используя внешнее, создав его с типом подключения `POSTGRES`. Так создается контроллер, который перенаправляет [TCP трафик](https://docs.amvera.ru/applications/configuration/network.html#tcp) на сервис доступа. Подключимся по внутреннему доменному имени из проекта, развернутого в Amvera с доступом к записи и чтению: ```python import psycopg2 conn = psycopg2.connect(dbname='dbname', user='postgres', password='passwd', host='amvera-username-cnpg-projectname-rw') ``` ### SQLite Файл базы данных SQLite всегда следует помещать в [постоянное хранилище Data](https://docs.amvera.ru/applications/storage.html#data), иначе данные могут потеряться при пересборке. Связано это с тем, что при сборке файлы из Code копируются в Artifacts - папку работающего приложения. Именно там и происходит взаимодействие с базой данных. А после пересборки файл перезапишется той версией, загруженной в Code. Загружать в /data нужно во вкладке "Репозиторий", выбрав папку Data в выпадающем списке и нажав кнопку "Загрузить данные". **Важно**: загрузить что либо в /data нельзя, если проект не развертывался. Для начала нужно собрать приложение. [Подробнее](https://docs.amvera.ru/applications/storage.html#data) После загрузки, получить доступ к файлу можно по пути `/data/<имя файла>` или, если вы меняли значение *persistenceMount*, то нужно заменить `/data` на введенное вами значение. На примере Python: ```python import sqlite3 connection = sqlite3.connect('/data/my_database.db') ``` ## Привязка GitHub Если вы хотите привязать сторонний git-сервис к проекту, то для этого вам понадобится создать и настроить вебхук для репозитория в git-сервисе. Разберем на примере GitHub. Перейдем во вкладку "Репозиторий" требуемого проекта. Там раскрываем блок "Подключить GitHub, GitLab, Bitbucket", сразу копируем URL и выбираем: - Git service - в нашем случае это GitHub - Ивент, при котором репозиторий Amvera будет делать git pull. При этом, если будет выбран и Push и CI ивенты, то репозиторий будет реагировать на CI ивент. - Добавьте секрет, либо сгенерируйте его через интерфейс - он нужен будет при подключении вебхука в GitHub. - Если ваш репозиторий приватный, добавьте значение "Токен", который создается в настройках аккаунта. - Вписываем ветку удаленного репозитория. Это нужно, если вы планируете использовать два проекта - Stag и Prod. По умолчанию будет ветка `master`. Нажимаем кнопку "подключить" и переходим в настройки репозитория GitHub, далее в настройки Webhook и вставляем скопированную ссылку в поле `Payload URL` и секрет в поле `Secret` и выберите Content-type: application/json. Включаем SSL верификацию, и выбираем "Send me **everything** ". Применяем изменения и теперь при пуше в ветку master GitHub репозитория будет выполняться git pull и сборка начнется автоматически. ## Stage/Prod проекты Для создания Stage/Prod проектов мы используем привязку различных веток стороннего Git-сервиса. Создадим два проекта и для каждого из них привяжем вебхук в репозитории. Для разделения на stage и prod, при привязке в интерфейсе Amvera укажем нужную ветку удаленного репозитория. Для prod - `prod` в первом проекте, для stage, соответственно, `stage` во втором проекте. В настройках репозитория GitHub создавать ветки не нужно. Теперь мы можем пушить изменения следующей командой: git push origin master:<имя-ветки> Например так: git push github master:prod И git pull выполнится только в требуемом проекте. ## Добавление переменных окружения Очень часто в проектах требуется использование переменных окружения, так как это удобно и безопасно. **Важно**: при сборке переменные окружения, указанные через интерфейс, недоступны. Перейдите во вкладку "Переменные" проекта. Там вы сможете создать секрет (переменная, значение которого нельзя увидеть через интерфейс) и обычную переменную. К примеру, создадим один секрет, содержащий токен и обычную переменную с именем. Доступ к переменным осуществляется через код. Например в Python можно получить доступ к переменной TOKEN следующим образом: ``` import os os.getenv("TOKEN") ``` Переменные из .env файла также будут подтягиваться. ## Соединение проектов по внутреннему доменному имени Все проекты, развернутые в Amvera можно связать по внутреннему доменному имени и 80 порту. К примеру, если мы хотим подключиться к PostgreSQL, развернутому в Amvera, как значение host нужно вписать внутреннее доменное имя из блока доменных имен вкладки "Настройки" проекта. ## Предварительная подготовка для развертывания каждого проекта - Написать YAML файл или Dockerfile. Для yaml у нас есть генератор, поддерживающий ограниченный набор окружений, в остальных случаях рекомендуется использовать [Dockerfile](https://docs.amvera.ru/books/amvera/page/docker). - Создать файл с зависимостями requirements.txt (для проектов на python) - Привязать репозиторий к Amvera - Сделать push в master ## Создание YAML файла (на примере для Python, для других языков процесс может отличаться) Подробно о том, как вручную составить файл конфигурации описано в [документации](../../applications/configuration/config-file.md). Мы же воспользуемся [автоматическим графическим инструментом генерации](https://manifest.amvera.ru/). ![python_config](../../img/python-tgbot.png) - Выбираем окружение Python и версию. - Указываем версию и путь до файла requirements.txt. Очень важно указать все используемые в проекте пакеты в этом файле, чтобы облако смогло их скачать через pip. - Указываем путь до файла, содержащего точку входа в программу (тот файл, который вы указываете интерпретатору питона, когда запускаете приложение). - Если в процессе работы ваш бот собирает какие-то данные от пользователя, которые следует сохранять на диск, то их следует класть в папку /data. В противном случае при перезапуске проекта все данные будут потеряны! - Порт можно указать любой, так как в нашем случае он не играет никакой роли (но в большинстве случаев мы рекомендуем использовать порт 80, именно он открыт в Amvera). - Нажимаем на кнопку Generate YAML, после чего начинается загрузка файла amvera.yml. - Скачанный файл кладем в корень нашего проекта. ## Создание файла с зависимостями (применимо для проектов на Python) - Cоздать файл `requirements.txt` , в котором прописать строчку: `python-telegram-bot` ```{eval-rst} .. admonition:: Внимание :class: attention В вашем проекте могут быть другие зависимости, отличающиеся от зависимостей в этом примере - их все нужно корректно прописать. ``` ```{eval-rst} .. admonition:: Подсказка :class: hint При развертывании телеграм-ботов частой ошибкой является неверное название "телебота" в `requirements.txt`. Телебот в `requirements.txt` должен называться `pyTelegramBotAPI`, а не `telebot`. ``` - Вызвать `pip install -r requirements.txt`, чтобы установить этот пакет. Почему бы просто не установить пакет через `pip install python-telegram-bot`? Так тоже можно, но файл requirements.txt все равно понадобится для разворачивания в облаке, поэтому лучше сразу его создать. - Проверить, что все работает, можно запустив бот локально через python3 echobot.py и протестировав созданный бот в телеграм (ссылку на бот можно найти у BotFather). - Поместить ваш `requirements.txt` в корень репозитория. ## Привязка git-репозитория и push в master Возможно три варианта: 1. Привязать к уже имеющемуся репозиторию (папке). - Инициализировать git репозиторий. Как установить [git](../../applications/git.rst), если он ещё не установлен, описано [тут](https://git-scm.com/book/ru/v2/%D0%92%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5-%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-Git). - В корне нашего проекта даем команду: `git init` (если гит уже инициализирован в вашем проекте, то этого делать не нужно) - Привязываем наш локальный гит репозиторий к удаленному репозиторию через команду, которая указана на странице проекта в amvera: ```shell git remote add amvera https://git.amvera.ru/<имя-пользователя>/<транслитерированное-имя-проекта>` ``` - Проверяем, что все изменения закомичены, вызывая `git status`. Если там будет список файлов, то значит нужно их закомитить, выполнив: ```shell git add . git commit -m "Some informative msg" ``` - Отправляем изменения в репозиторий Amvera ```shell git push amvera master ``` На запрос пользователя и пароля укажите имя пользователя и пароль вашей учетной записи Amvera. 2. Использовать выделенный репозиторий Amvera (а не привязывать свой). - Склонируем пустой репозиторий: ```shell git clone https://git.amvera.ru/<имя-пользователя>/<транслитерированное-имя-проекта> ``` - Проверяем, что все изменения закомичены, вызывая `git status`. Если там будет список файлов, то значит нужно их закомитить, выполнив: ```shell git add . git commit -m "Some informative msg" ``` - Отправляем изменения в репозиторий Amvera ```shell git push amvera master ``` На запрос пользователя и пароля укажите имя пользователя и пароль вашей учетной записи Amvera. 3. Привязка GitHub/GitLab как показано выше в инструкции ## Развертывание приложения После того как проект запушится в систему, начнется [сборка](../../applications/build.md) и на странице проекта статус поменяется на "Выполняется сборка". Как только проект соберется, он перейдет в стадию [запуска](../../applications/run.md) и статус сменится на "Выполняется развертывание", а после перейдет в "Успешно развернуто". Если по какой-то причине проект не развернулся, можно обратиться к логам сборки и логам приложения для отладки (они могут идти с задержкой в 5-10 минут). Если Проект завис в статусе "Сборка" на долгое время, а логи сборки не отображаются, то стоит ещё раз проверить корректность `amvera.yaml` файла и `requirements.txt`(только в случае с Python) файла. ```{eval-rst} .. admonition:: Подсказка :class: hint Если логи пишутся в print, для их отображения надо выставить переменную окружения `PYTHONUNBUFFERED` в 1. ``` ```{eval-rst} .. admonition:: Важно :class: warning Сохраняйте файлы БД и иные изменяемые данные в постоянное хранилище, чтобы избежать их потери при обновлении проекта, когда производится "откат" папки код до состояния обновления репозитория. Папка data в корне проекта и директория /data, это разные директории. Проверить, что сохранение идет в /data, можно зайдя в папку "data" на странице "Репозиторий". ``` ```{eval-rst} .. admonition:: Важно :class: warning Чтобы избежать ошибки 502, измените в вашем коде host 127.0.0.1 (или подобный localhost) на 0.0.0.0, и пропишите в конфигурации порт, который слушает ваше приложение (пример - 8080). ``` ## Если у вас не получается развернуть проект Напишите наблюдаемую вами симптоматику на support@amvera.ru с указанием вашего имени пользователя и названия проекта, мы постараемся вам помочь.