Подключение нового учебного заведения¶
Содержание
Создание сообщества¶
Ботов ВКонтакте можно привязывать только к группам. Для её создания перейдите в раздел сообществ из бокового меню:
Там нажмите на кнопку «Создать сообщество»
В открывшемся меню выберите «Группа по интересам»
На ваше усмотрение заполните данные группы
Перейдите в раздел «Управление» нового сообщества
Затем в подраздел «Работа с API»
Здесь нужно создать токен сообщества со следующими правами:
управление сообществом, сообщения сообщества, фотографии, документы, стена
Скопируйте себе этот токен, в дальнейшем он нам понадобится.
Предупреждение
Никому не передавайте этот токен! Он позволяет управлять вашим сообществом
Перейдите во вкладку Long Poll API и включите его. Выберите версию API 5.103
Затем во вкладке типы событий установите все галочки
Далее, в разделе «Сообщения» нужно включить сообщения сообщества.
По желанию можно настроить приветствие. Это сообщение, которое получит пользователь, впервые открывший диалог с ботом.
Нажмите «Сохранить».
Затем, в подразделе «Настройки для бота» включите «Возможности ботов» и выберите обе галочки.
Снова нажмите «Сохранить»
Создайте отдельную беседу для тестирования и обучения администраторов.
Вернитесь к сообществу. У вас появится меню с одной кнопкой - «Добавить в беседу».
Нажмите на неё и выберите обе беседы, в которых должен работать бот.
Вернитесь к беседам. Откройте список участников и найдите среди них своего бота. Сделайте его администратором беседы, чтобы дать ему доступ на написание сообщений в этой беседе. (это может сделать только действующий администратор или создатель)
Это действие нужно повторить с обоими беседами.
Получение токена пользователя¶
Токен пользователя необходми для автоматической смены статуса группы с номером версии.
См.также
Документация ВКонтакте о получении токена пользователя https://vk.com/dev/implicit_flow_user
Настройка компьютера для работы¶
Зарегистрируйтесь на Github, если у вас еще нет там аккаунта (он понадобится для получения уведомлений о выходе новых версий)
Перейдите на страницу с репозиторием нажмите кнопку Watch, чтобы получать уведомления об обновлениях на электропочту. Выберите вариант Releases only, если не собираетесь участвовать в развитии основной ветки проекта
Затем нажмите кнопку Fork. Репозиторий скопируется в ваш аккаунт. Далее вы будете работать из своей копии.
Установите Git на свой компьютер.
Для Windows используйте Git For Windows
В Linux используйте стандартный менеджер пакетов
sudo pacman -S git # В Arch
или
sudo apt install git # В Ubuntu
Настройте Git
git config --global user.name ваше_имя git config --global user.email ваша_электропочта_с_github
Установите Python, если он еще не установлен
(В установщике для Windows важно указать галочку Add Python to PATH)
Установите PostgreSQL
Для Windows
Для Linux:
sudo apt install postgresql postgresql-contrib # Ubuntu
sudo pacman -S postgresql # Arch
Получение исходного кода бота¶
Создайте папку в которой будет хранится исходный код бота. Перейдите в нее из командной строки.
Загрузите последнюю доступную версию бота:
git clone https://github.com/ваш_ник/ralph cd ralph
Настройка переменных окружения¶
Переменные окружения - это особый файл с секретными данными, которые нельзя нигде публиковать.
В случае с Ральфом там хранится токен сообщества, токен администратора, URL доступа к базе данных, и для удобства - настройки модуля логгирования, идентификатор сообщества с ботом.
Создайте в папке с исходным кодом файл .env (Именно начинающийся с точки. В Windows могут возникнуть проблемы с этим, тогда создайте файл из IDE)
Вот готовый шаблон файла с переменными окружения:
DATABASE_URL="<ссылка доступа к базе данных. Ниже будет сказано, как её получить>"
GID_ID="<идентификатор группы с ботом>"
LOG_FMT="%(levelname)s: %(message)s" # Формат логов
LOG_LEVEL="20" # Уровень логгирования. Указывает на то, логи какого уровня печатать. Подробнее здесь: `<https://docs.python.org/3/library/logging.html#levels>`_
VK_TOKEN="<токен сообщества>"
VK_USER_TOKEN="<токен администратора. Нужен для автоматического изменения номера версии в статусе группы>"
В случае, если вы работаете в PyCharm для локального запуска бота вы можете использовать расширение EnvFile (Без него вы будете получать ошибку KeyError, говорящую о том, что не была найдена переменная окружения)
Настройка хостинга¶
Я предлагаю использовать в качестве хостинга Heroku. У них есть бесплатный тариф, но с ограничением по трафику в 550 часов / месяц. По моему опыту этого достаточно. Для работы с Heroku нужно:
зарегистрировать аккаунт
установить CLI
Все действия из списка ниже нужно выполнять в папке Ralph со всеми исходниками бота
Авторизуемся в CLI:
heroku auth
Создаём приложение:
heroku create
Имя приложения будет сгенерировано автоматически.
Подключаем к приложению базу данных PostgreSQL:
heroku addons:create heroku-postgresql:hobby-dev
Получим ссылку для доступа к базе данных
heroku config:get DATABASE_URL
Скопируем всю ссылку и вставим в файл .env
Настроим переменные окружения на сервере:
heroku config:set GID_ID=идентификатор вашей группы
heroku config:set LOG_FMT=%(levelname)s: %(message)s
heroku config:set LOG_LEVEL=20
heroku config:set VK_TOKEN=токен сообщества
heroku config:set VK_USER_TOKEN=токен администратора
Настройка виртуального окружения¶
Создадим виртуальное окружение в папке с ботом
python -m venv venv
Активируем его
На Windows:
venv/Scripts/activate
На Linux:
source venv/bin/activate
Настройка базы данных¶
Для того чтобы скопировать нужную для работы бота структуру БД в вашу копию бота:
Откройте файл db.pgsql
Замените все вхождения «user» на имя вашего пользователя
Примечание
Структура ссылки, получаемой от Heroku: postgres://username:password@localhost/db_name
Вам нужно скопировать выделенную часть из вашей ссылки в меню Замена в редакторе
Примените дамп из файла db.pgsql
В Linux:
psql $DATABASE_URL < db.pgsql
В Windows:
psql %DATABASE_URL% < db.psql
После выполнения этой команды вы получите чистую БД с необходимой структурой
Модификация кода¶
Код написан без жёсткой привязки к конкретному учереждению. Его можно легко адаптировать под любые нужды.
Модуль получения расписания хранится в файле scheduler.py.
Документация по этому модулю находится в отдельном файле.
Так же, для локального тестирования нужно создать файл .env, где будут записаны переменные окружения.
Чтобы сохранить в репозитории сделанные изменения, нужно сделать коммит:
Сохраним изменения:
git add .
И создадим коммит:
git commit -m "<краткое описание сделанных вами изменений>"
Отправим изменения на сервер
git push origin master
Выгрузка на хостинг¶
Редактированный код можно выгрузить на сервер:
git push heroku master
И запустить:
heroku ps:scale bot=1 sch=1
Загрузка исходного кода веб-интерфейса¶
Создайте папку в которой будет хранится исходный код веб-интерфейса. (Она не должна находиться в папке с ботом) Перейдите в нее из командной строки.
Загрузите последнюю доступную версию веб-интерфейса:
git clone https://github.com/dadyarri/ralph_cms cd ralph_cms
Скопируйте файл .env из папки с ботом в папку с веб-интерфейсом
Выгрузка веб-интерфейса на сервер¶
Создаём приложение:
heroku create
Имя приложения будет сгенерировано автоматически.
Настроим переменные окружения на сервере:
heroku config:set GID_ID=идентификатор вашей группы
heroku config:set LOG_FMT=%(levelname)s: %(message)s
heroku config:set LOG_LEVEL=20
heroku config:set VK_TOKEN=токен сообщества
heroku config:set VK_USER_TOKEN=токен администратора
heroku config:set DATABASE_URL=ссылка из файла .env
Теперь код можно выгрузить на сервер. Запуск произойдет автоматически:
git push heroku master
Бот готов к работе. Теперь осталось создать группу со студентами и настроить её.
См.также