vk-toot/README.rst

==================
vk-mastodon-bridge
==================

Бридж для кросспостинга из `VK`_ в `Mastodon`_. Это приложение будет дублировать посты из паблика или публичной группы VK в аккаунт Mastodon.

Пример аккаунта бота: `@jrokku@mas.to`_

.. _VK: https://vk.com/
.. _Mastodon: https://joinmastodon.org/
.. _jrokku@mas.to: https://mas.to/@jrokku


Как это работает
================

Скрипт согласно заданному промежутку времени (см. ниже ``POLLING_TIME``) ходит в API VK и забирает оттуда самый свежий пост, запоминает его ID в файл. Затем ходит в API Mastodon и создаёт новый пост, который содержит оригинальный текст поста, ссылку на оригинальный пост, ссылки на каждое вложение из оригинального поста.

TODO
----

- Не учитывается длина поста. Если исходный пост не будет укладываться в лимит символов на инстансе Mastodon'а, то неизвестно что произойдёт. Решение: надо обрезать текст поста в функции ``build_post()``.
- Никак не обрабатываются вложения типов отличных от фото (`photo`) и фотоальбома (`album`).

Настройки и запуск
==================

API Mastodon
------------

Для получения токена API Mastodon достаточно добавить приложение в своём профиле (Preferences -> Development). Из разрешений достаточно `write` для создания постов, ничего другого бридж делать не умеет.

API VK
------

Нужно добавить приложение на https://dev.vk.com. Будет получен ``APP_ID``.

Для получения бессрочного токена перейти по ссылке следующего вида::

    https://oauth.vk.com/authorize?client_id=12345678&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=offline&response_type=token&v=5.131

Здесь параметр ``client_id`` равняется ``APP_ID`` приложения, ``scope=offline`` задаёт нулевой (бесконечный) срок жизни токена.

При переходе по ссылке произойдёт редирект на страницу с подтверждением выдачи доступа приложению и далее редирект на страницу с предупреждением. Нас интересует значение query-параметра ``access_token`` в адресной строке.

Это всё также описано в документации к API: https://dev.vk.com/api/access-token/implicit-flow-user

Переменные окружения
--------------------

Нужно задать все переменные окружения. Удобный способ — в файле ``.env`` и экспортировать в шэлл.

========================= =============================== =========================================================
Переменная окружения      Пример                          Описание
========================= =============================== =========================================================
MASTODON_API_URL          https://mastodon.social/api/v1  URL адрес API Mastodon.
MASTODON_API_ACCESS_TOKEN                                 Ключ API Mastodon.
VK_API_URL                https://api.vk.com/method       URL API VK.
VK_API_VERSION            5.131                           Версия VK API.
VK_API_ACCESS_TOKEN                                       Ключ API VK.
VK_GROUP_DOMAIN           apiclub                         slug адрес группы/паблика VK.
POLLING_TIME              300                             Количество секунд между получением постов. Умолчание: 300.
========================= =============================== ==========================================================

Запуск
------

::

    pip -r requirements.txt
    source .env
    python vk-mastodon-bridge.py

Docker
------

::

    sudo docker build -t vk-mastodon-bridge:0.2.0 .
    sudo docker run --detach \
        --name vk-mastodon-bridge \
        --volume /opt/vk-mastodon-bridge/data:/opt/vk-mastodon-bridge/data \
        vk-mastodon-bridge:0.2.0

История изменений
=================

0.2.0
-----

- Реализована загрузка вложений в Mastodon (до 4-х штук). Только изображения.
- Обновлён путь до приложения в Dockerfile
- Изменено место хранения файла last_post_id, теперь он в директории data, откуда его можно удобно монтировать как Docker volume

0.1.0
-----

Initial release.