Mini Apps со stage и prod, привязкой GitHub, БД и связкой Backend и Frontend, развернутых в разных проектах

Развертывание Backend + Frontend + Database (PostgreSQL | SQLite)

Для работы web приложения, состоящего из Backend, Frontend и базы данных, в Amvera вам нужно создать отдельные проекты для каждого из частей веб приложения и связать их по доменному имени. Причем, можно связать как по внутреннему доменному имени, так и внешнему.

К примеру, можно отправлять запросы к 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), следуйте этой инструкции.

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

Получившийся адрес копируем и отправляем BotFather (или вставляем в коде как webApp) для привязки.

Подключение БД (PostgreSQL или SQLite)

PostgreSQL

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

Подключимся по внутреннему доменному имени из проекта, развернутого в Amvera с доступом к записи и чтению:

import psycopg2

conn = psycopg2.connect(dbname='dbname', user='postgres', password='passwd', host='amvera-username-cnpg-projectname-rw')

SQLite

Файл базы данных SQLite всегда следует помещать в постоянное хранилище Data, иначе данные могут потеряться при пересборке. Связано это с тем, что при сборке файлы из Code копируются в Artifacts - папку работающего приложения. Именно там и происходит взаимодействие с базой данных. А после пересборки файл перезапишется той версией, загруженной в Code.

Загружать в /data нужно во вкладке «Репозиторий», выбрав папку Data в выпадающем списке и нажав кнопку «Загрузить данные».

Важно: загрузить что либо в /data нельзя, если проект не развертывался. Для начала нужно собрать приложение. Подробнее

После загрузки, получить доступ к файлу можно по пути /data/<имя файла> или, если вы меняли значение persistenceMount, то нужно заменить /data на введенное вами значение.

На примере 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.

  • Создать файл с зависимостями requirements.txt (для проектов на python)

  • Привязать репозиторий к Amvera

  • Сделать push в master

Создание YAML файла (на примере для Python, для других языков процесс может отличаться)

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

python_config

  • Выбираем окружение Python и версию.

  • Указываем версию и путь до файла requirements.txt. Очень важно указать все используемые в проекте пакеты в этом файле, чтобы облако смогло их скачать через pip.

  • Указываем путь до файла, содержащего точку входа в программу (тот файл, который вы указываете интерпретатору питона, когда запускаете приложение).

  • Если в процессе работы ваш бот собирает какие-то данные от пользователя, которые следует сохранять на диск, то их следует класть в папку /data. В противном случае при перезапуске проекта все данные будут потеряны!

  • Порт можно указать любой, так как в нашем случае он не играет никакой роли (но в большинстве случаев мы рекомендуем использовать порт 80, именно он открыт в Amvera).

  • Нажимаем на кнопку Generate YAML, после чего начинается загрузка файла amvera.yml.

  • Скачанный файл кладем в корень нашего проекта.

Создание файла с зависимостями (применимо для проектов на Python)

  • Cоздать файл requirements.txt , в котором прописать строчку: python-telegram-bot

    Внимание

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

    Подсказка

    При развертывании телеграм-ботов частой ошибкой является неверное название «телебота» в 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, если он ещё не установлен, описано тут.

    • В корне нашего проекта даем команду: git init (если гит уже инициализирован в вашем проекте, то этого делать не нужно)

    • Привязываем наш локальный гит репозиторий к удаленному репозиторию через команду, которая указана на странице проекта в amvera:

      git remote add amvera https://git.amvera.ru/<имя-пользователя>/<транслитерированное-имя-проекта>`

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

      git add .
git commit -m "Some informative msg"

    • Отправляем изменения в репозиторий Amvera

      git push amvera master

      На запрос пользователя и пароля укажите имя пользователя и пароль вашей учетной записи Amvera.

  2. Использовать выделенный репозиторий Amvera (а не привязывать свой).

    • Склонируем пустой репозиторий:

      git clone https://git.amvera.ru/<имя-пользователя>/<транслитерированное-имя-проекта>

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

      git add .
git commit -m "Some informative msg"

    • Отправляем изменения в репозиторий Amvera

      git push amvera master

      На запрос пользователя и пароля укажите имя пользователя и пароль вашей учетной записи Amvera.

  3. Привязка GitHub/GitLab как показано выше в инструкции

Развертывание приложения

После того как проект запушится в систему, начнется сборка и на странице проекта статус поменяется на «Выполняется сборка».

Как только проект соберется, он перейдет в стадию запуска и статус сменится на «Выполняется развертывание», а после перейдет в «Успешно развернуто».

Если по какой-то причине проект не развернулся, можно обратиться к логам сборки и логам приложения для отладки (они могут идти с задержкой в 5-10 минут). Если Проект завис в статусе «Сборка» на долгое время, а логи сборки не отображаются, то стоит ещё раз проверить корректность amvera.yaml файла и requirements.txt(только в случае с Python) файла.

Подсказка

Если логи пишутся в print, для их отображения надо выставить переменную окружения PYTHONUNBUFFERED в 1.

Важно

Сохраняйте файлы БД и иные изменяемые данные в постоянное хранилище, чтобы избежать их потери при обновлении проекта, когда производится «откат» папки код до состояния обновления репозитория. Папка data в корне проекта и директория /data, это разные директории.

Проверить, что сохранение идет в /data, можно зайдя в папку «data» на странице «Репозиторий».

Важно

Чтобы избежать ошибки 502, измените в вашем коде host 127.0.0.1 (или подобный localhost) на 0.0.0.0, и пропишите в конфигурации порт, который слушает ваше приложение (пример - 8080).

Если у вас не получается развернуть проект

Напишите наблюдаемую вами симптоматику на support@amvera.ru с указанием вашего имени пользователя и названия проекта, мы постараемся вам помочь.