Подключение нового учебного заведения

Создание сообщества

Ботов ВКонтакте можно привязывать только к группам. Для её создания перейдите в раздел сообществ из бокового меню:

Сообщества

Там нажмите на кнопку «Создать сообщество»

Создать сообщество

В открывшемся меню выберите «Группа по интересам»

Выбор типа группы

На ваше усмотрение заполните данные группы

Заполнение данных

Перейдите в раздел «Управление» нового сообщества

Кнопка Управление

Затем в подраздел «Работа с API»

Здесь нужно создать токен сообщества со следующими правами:

управление сообществом, сообщения сообщества, фотографии, документы, стена

Создание токена

Скопируйте себе этот токен, в дальнейшем он нам понадобится.

Предупреждение

Никому не передавайте этот токен! Он позволяет управлять вашим сообществом

Перейдите во вкладку Long Poll API и включите его. Выберите версию API 5.103

Параметры Long Poll API

Затем во вкладке типы событий установите все галочки

Далее, в разделе «Сообщения» нужно включить сообщения сообщества.

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

Нажмите «Сохранить».

Настройка сообщений

Затем, в подразделе «Настройки для бота» включите «Возможности ботов» и выберите обе галочки.

Настройка сообщений

Снова нажмите «Сохранить»

Создайте отдельную беседу для тестирования и обучения администраторов.

Вернитесь к сообществу. У вас появится меню с одной кнопкой - «Добавить в беседу».

Меню

Нажмите на неё и выберите обе беседы, в которых должен работать бот.

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

Это действие нужно повторить с обоими беседами.

Получение токена пользователя

Токен пользователя необходми для автоматической смены статуса группы с номером версии.

См.также

Документация ВКонтакте о получении токена пользователя https://vk.com/dev/implicit_flow_user

Настройка компьютера для работы

  1. Зарегистрируйтесь на Github, если у вас еще нет там аккаунта (он понадобится для получения уведомлений о выходе новых версий)

  2. Перейдите на страницу с репозиторием нажмите кнопку Watch, чтобы получать уведомления об обновлениях на электропочту. Выберите вариант Releases only, если не собираетесь участвовать в развитии основной ветки проекта

  3. Затем нажмите кнопку Fork. Репозиторий скопируется в ваш аккаунт. Далее вы будете работать из своей копии.

  4. Установите Git на свой компьютер.

    Для Windows используйте Git For Windows

    В Linux используйте стандартный менеджер пакетов

    sudo pacman -S git # В Arch
    

    или

    sudo apt install git # В Ubuntu
    
  5. Настройте Git

    git config --global user.name ваше_имя
    
    git config --global user.email ваша_электропочта_с_github
    
  6. Установите Python, если он еще не установлен

    (В установщике для Windows важно указать галочку Add Python to PATH)

  7. Установите PostgreSQL

    Для Windows

    Для Linux:

    sudo apt install postgresql postgresql-contrib # Ubuntu
    
    sudo pacman -S postgresql # Arch
    

Получение исходного кода бота

  1. Создайте папку в которой будет хранится исходный код бота. Перейдите в нее из командной строки.

  2. Загрузите последнюю доступную версию бота:

    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 нужно:

Все действия из списка ниже нужно выполнять в папке Ralph со всеми исходниками бота

  1. Авторизуемся в CLI:

heroku auth
  1. Создаём приложение:

heroku create

Имя приложения будет сгенерировано автоматически.

  1. Подключаем к приложению базу данных PostgreSQL:

heroku addons:create heroku-postgresql:hobby-dev
  1. Получим ссылку для доступа к базе данных

heroku config:get DATABASE_URL
  1. Скопируем всю ссылку и вставим в файл .env

  2. Настроим переменные окружения на сервере:

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=токен администратора

Настройка виртуального окружения

  1. Создадим виртуальное окружение в папке с ботом

    python -m venv venv
    
  2. Активируем его

    На Windows:

    venv/Scripts/activate
    

    На Linux:

    source venv/bin/activate
    

Настройка базы данных

Для того чтобы скопировать нужную для работы бота структуру БД в вашу копию бота:

  1. Откройте файл db.pgsql

  2. Замените все вхождения «user» на имя вашего пользователя

Примечание

Структура ссылки, получаемой от Heroku: postgres://username:password@localhost/db_name

Вам нужно скопировать выделенную часть из вашей ссылки в меню Замена в редакторе

  1. Примените дамп из файла 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

Выгрузка на хостинг

  1. Редактированный код можно выгрузить на сервер:

git push heroku master
  1. И запустить:

heroku ps:scale bot=1 sch=1

Загрузка исходного кода веб-интерфейса

  1. Создайте папку в которой будет хранится исходный код веб-интерфейса. (Она не должна находиться в папке с ботом) Перейдите в нее из командной строки.

  2. Загрузите последнюю доступную версию веб-интерфейса:

    git clone https://github.com/dadyarri/ralph_cms
    
    cd ralph_cms
    
  3. Скопируйте файл .env из папки с ботом в папку с веб-интерфейсом

Выгрузка веб-интерфейса на сервер

  1. Создаём приложение:

heroku create

Имя приложения будет сгенерировано автоматически.

  1. Настроим переменные окружения на сервере:

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
  1. Теперь код можно выгрузить на сервер. Запуск произойдет автоматически:

git push heroku master

Бот готов к работе. Теперь осталось создать группу со студентами и настроить её.