XPostr

This is a standalone Telegram -> VK crossposting app. It can handle multiple user accounts in Telegram and VK.

• Requirements
• Installation
  • prereqisites
  • backend
  • frontend
• Configuring
  • API keys
    • Telegram
    • VK
  • application config: config.ini
  • systemd unit
  • uwsgi application
  • nginx
• Application architecture
• Known issues
• TODO

Requirements

To run backend:

• Python 3.6 (3.7 recommended)
• uwsgi, uwsgi-plugin-python3, python3-pip apt packages
• pipenv pip package

If you plan to build frontent:

• npm/yarn
• quasar (https://v1.quasar-framework.org/quasar-cli/installation)

Installation

prereqisites

• Make sure you have Python 3.7 installed or if you don't want to (or can't) install it, change Pipfile

  [requires]
  python_version = "3.7"

  to

  [requires]
  python_version = "3.6"

  There is no dependencies on 3.7 changes, it's just a recommendation for performance reasons.

• Make sure you have latest version of pip installed! Otherwise it can crash with weird exceptions during installation.

  apt install python3-pip
  pip install -U pip # this is important!
  

• Install pipenv, locally or globally. Add --user option to install locally.

  pip install -U pipenv
  

• If you want to install uwsgi globally, install packages uwsgi and uwsgi-plugin-python3.

• If you want to run uwsgi from your virtualenv -- see next step.

backend

• Go to directory where you unpacked application source code. You should see Pipfile and Pipfile.lock there.
• Install dependencies:

  pipenv install
  

• If you decided to run uwsgi from your virtualenv -- execute pipenv install uwsgi
• Get your virtualenv path, you'll need it later

  pipenv --venv
  

frontend

• Unpack frontend/dist.tar.gz to your web-root directory

• Make sure to create symlink statics/avatars pointing to your avatars path or set paths.avatars to point to statics/avatars. See application config step.

  If you want to build frontend code from source:

  • install npm or yarn
  • install Quasar cli
  • go to frontend/ directory
  • use quasar dev to run development server or quasar build to build a release version

Configuring

API keys

First you need to register your applications on Telegram and VK.

Telegram

• Open https://my.telegram.org and authorize there/
• In API development tools you'll see your api_id and api_hash -- save them for next step.

VK

• Open https://vk.com/apps?act=manage.
• Create new application, choose Standalone as type -- this is important!
• Open Settings from the left-side menu.
• You'll see your Application ID and Secret key -- these are your client_id and client_secret respectively, save them for next step.
• Change Application state to enabled and save your changes.

application config: config.ini

Go to backend directory. Copy config.ini.sample to config.ini and make changes in sections:

• jwt: fill secret with some random string (f.e. get it with dd if=/dev/urandom count=1 bs=64 2>/dev/null | base64)
• vk: specify your client_id and client_secret
• telegram: specify your api_id and api_hash. avatars_path is a relative uri, set it to your avatars directory relative to web server document root
• paths: adjust if needed
  • db_auth and db_main are full paths to sqlite database files (will be created), directories must be writable
  • avatars -- full path to directory where avatars will be downloaded, must be writable
  • sessions -- full path to directory where Telegram client will store it's session files, must be writable
  • temp -- just a temporary directory, might not exist, but path to it must be writable
  • daemon_socket -- full path to a daemon unix socket, directory must be writable

systemd unit

Go to etc/systemd/system directory.

• Copy xpostr-daemon.service.sample to xpostr-daemon.service.
• Replace YOUR_USER, APPLICATION_PATH and VENV_PATH with corresponding values.
• Put xpostr-daemon.service file to /etc/systemd/system
• Execute systemctl daemon-reload for systemd to pick up new unit
• Enable (for autostart) and start it:

  systemctl enable xpostr-daemon
  systemctl start xpostr-daemon
  

uwsgi application

Go to etc/uwsgi/apps-available. Copy xpostr-web.ini.sample to xpostr-web.ini. Replace APPLICATION_PATH, VENV_PATH and USER with corresponding values.

Now, if you want to run uwsgi from virtualenv -- repeat previous part steps replacing all mentions of xpostr-daemon with xpostr-web.

Or, if you use uwsgi installed from apt, add your app:

cp etc/uwsgi/apps-available/xpostr-web.ini /etc/uwsgi/apps-available
ln -s /etc/uwsgi/apps-available/xpostr-web.ini /etc/uwsgi/apps-enabled
systemctl restart uwsgi

nginx

Use etc/nginx/sites-available/xpostr-web.conf.sample as a reference to configure your web server.

There is no reason to keep web ui files at frontend/dist/spa. You can place them anywhere you wish, just remember to adjust telegram.avatars (and possibly paths.avatars) in config.ini respectively.

Application architecture

TODO

Known issues

• Non user-friendly VK authentication process: unfortunately VK has crippled permission system, so some API are available only if redirect_uri of OAuth process is points to api.vk.com (so called standalone applications).
• Wide permission list for VK: unfortunately VK has crippled permission system -- 1 permission controls 1 API method. Regardless of where you plan to post, to user personal feed or to any of his groups, you need to get one permission to access all of them. Same for photos/documents.
• Complete Telegram authentication process: unfortunately Telegram restricts bots from reading channel messages (even for public ones), so need to use Client API here with complete authentication process.
• Telegram voice messages: uploads successfully but VK doesn't attach them, so message looks empty (probably also need conversion to MP3).
• Telegram message media: sometimes telegram server kicks client when downloading media -- this may lead to missing attachment or fail to post to VK.
• Web UI: On JWT expiration authorized state isn't preperly reset
• Web UI: Dropdowns in Create new dialog are cropped to dialog borders. Quasar issue, waiting for fix partially fixed as of v1.0.0-b15.

TODO

• handle case when Telegram user revokes app access from another client
• handle case when VK user revokes app access after it's been granted
• replace requests with aiohttp
• add transitions use in UI
• implement token refresh in UI
• logging config
• per connection settings:
  • add/attach forwarded from
  • add/attach 'in reply to'
  • some basic filtering
• backend lib.xpost is a bloody mess. refactor it
• merge web-service with daemon code?