|
1 | | -# Yandex.Disk Telegram Bot |
| 1 | +<h1 align="center"> |
| 2 | + Yandex.Disk in Telegram |
| 3 | +</h1> |
| 4 | + |
| 5 | +<p align="center"> |
| 6 | + A bot for Telegram that integrates Yandex.Disk right into Telegram. |
| 7 | +</p> |
| 8 | + |
| 9 | + |
| 10 | +## Content |
| 11 | + |
| 12 | +- [Content](#content) |
| 13 | +- [Features](#features) |
| 14 | +- [Requirements](#requirements) |
| 15 | +- [Installation](#installation) |
| 16 | +- [Integration with external API's](#integration-with-external-apis) |
| 17 | + - [Telegram](#telegram) |
| 18 | + - [Yandex.Disk](#yandexdisk) |
| 19 | +- [Local usage](#local-usage) |
| 20 | + - [Server](#server) |
| 21 | + - [Database](#database) |
| 22 | +- [Deployment](#deployment) |
| 23 | + - [Heroku](#heroku) |
| 24 | +- [Contribution](#contribution) |
| 25 | +- [License](#license) |
| 26 | + |
| 27 | + |
| 28 | +## Features |
| 29 | + |
| 30 | +- uploading of photos; |
| 31 | +- uploading of files; |
| 32 | +- uploading of audio; |
| 33 | +- uploading of video; |
| 34 | +- uploading of voice; |
| 35 | +- creating of folders. |
| 36 | + |
| 37 | + |
| 38 | +## Requirements |
| 39 | + |
| 40 | +- [python 3.8+](https://www.python.org/) |
| 41 | +- [pip](https://pypi.org/project/pip/) |
| 42 | +- [venv](https://docs.python.org/3/library/venv.html) |
| 43 | +- [git](https://git-scm.com/) |
| 44 | +- [curl](https://curl.haxx.se/) (optional) |
| 45 | +- [nginx](https://nginx.org/) (optional) |
| 46 | +- [postgreSQL 10+](https://www.postgresql.org/) (optional) |
| 47 | +- [heroku](https://www.heroku.com/) (optional) |
| 48 | + |
| 49 | +It is expected that all of the above software is available as a global variable: `python3`, [`python3 -m pip`](https://github.com/pypa/pip/issues/5599#issuecomment-597042338), `python3 -m venv`, `git`, `curl`, `nginx`, `psql`, `heroku`. |
| 50 | + |
| 51 | +If you want to host this server somewhere, then you need install additional software. See your host installation guide. |
| 52 | + |
| 53 | +All subsequent instructions is for Unix systems (primarily for Linux). You may need to make some changes on your own if you work on Windows. |
| 54 | + |
| 55 | + |
| 56 | +## Installation |
| 57 | + |
| 58 | +1. Clone this repository. |
| 59 | + |
| 60 | +```shell |
| 61 | +git clone https://github.com/Amaimersion/yandex-disk-telegram-bot.git |
| 62 | +cd yandex-disk-telegram-bot |
| 63 | +``` |
| 64 | + |
| 65 | +2. Create virtual environment. |
| 66 | + |
| 67 | +```shell |
| 68 | +python3 -m venv venv |
| 69 | +source ./venv/bin/activate |
| 70 | +``` |
| 71 | + |
| 72 | +Run `deactivate` when you end in order to exit from virtual environment. |
| 73 | + |
| 74 | +After that step we will use `python` instead of `python3` and `pip` instead of `python3 -m pip`. If for some reason you don't want create virtual environment, then: |
| 75 | +- use `python3` and `python3 -m pip` |
| 76 | +- edit executable paths in `.vscode/settings.json` |
| 77 | +- edit names in `./scripts` files |
| 78 | + |
| 79 | +You may also want to upgrade `pip`, because [there can be](https://github.com/pypa/pip/issues/5221) an old version (9.0.1) instead of new one. Run `pip install --upgrade pip`. |
| 80 | + |
| 81 | +3. Install requirements. |
| 82 | + |
| 83 | +```shell |
| 84 | +./scripts/requirements/install.sh |
| 85 | +``` |
| 86 | + |
| 87 | +4. If you want to use database locally, then make DB upgrade: |
| 88 | + |
| 89 | +```shel |
| 90 | +source ./scripts/env/development.sh |
| 91 | +flask db upgrade |
| 92 | +``` |
| 93 | + |
| 94 | +5. Run this to see more actions: |
| 95 | + |
| 96 | +`python manage.py --help` |
| 97 | + |
| 98 | +6. If needed, perform [integration with external API's](#integration-with-external-apis). |
| 99 | + |
| 100 | +7. See [Local usage](#local-usage) or [Deployment](#deployment). |
| 101 | + |
| 102 | + |
| 103 | +## Integration with external API's |
| 104 | + |
| 105 | +### Telegram |
| 106 | + |
| 107 | +1. Register your bot in chat with [@BotFather](http://t.me/BotFather) and get API token. |
| 108 | + |
| 109 | +2. [Set a webhook](https://core.telegram.org/bots/api#setwebhook): |
| 110 | +```shell |
| 111 | +./scripts/telegram/set_webhook.sh <TELEGRAM_BOT_TOKEN> <SERVER_URL> <MAX_CONNECTIONS> |
| 112 | +``` |
| 113 | + |
| 114 | +Russian users may need a proxy: |
| 115 | +```shell |
| 116 | +./scripts/telegram/set_webhook.sh <TELEGRAM_BOT_TOKEN> <SERVER_URL> <MAX_CONNECTIONS> "--proxy <PROXY>" |
| 117 | +``` |
| 118 | + |
| 119 | +For parameter `MAX_CONNECTIONS` it is recommended to use maxium number of simultaneous connections to the selected database. For example, "Heroku Postgres" extension at "Hobby Dev" plan have connection limit of 20. So, you should use `20` as value for key `MAX_CONNECTIONS` in order to avoid possible problems with `too many connections` error. |
| 120 | + |
| 121 | +From Telegram documentation: |
| 122 | +> If you'd like to make sure that the Webhook request comes from Telegram, we recommend using a secret path in the URL, e.g. `https://www.example.com/<token>`. Since nobody else knows your bot‘s token, you can be pretty sure it’s us. |
| 123 | +
|
| 124 | +So, instead of `/telegram_bot/webhook` you can use something like this `/telegram_bot/webhook_fd1k3Bfa01WQl5S`. |
| 125 | + |
| 126 | +### Yandex.Disk |
| 127 | + |
| 128 | +1. Register your app in [Yandex](https://yandex.ru/dev/oauth/). |
| 129 | + |
| 130 | +2. Most likely it will take a while for Yandex moderators to check your app. |
| 131 | + |
| 132 | +3. Get your app ID and password at special Yandex page for your app. |
| 133 | + |
| 134 | +4. At special Yandex page for your app find "Callback URI" settings and add this URI: `https://<your site>/telegram_bot_yandex_disk_auth`. |
| 135 | + |
| 136 | + |
| 137 | +## Local usage |
| 138 | + |
| 139 | +### Server |
| 140 | + |
| 141 | +This WSGI App uses `gunicorn` as WSGI HTTP Server and `nginx` as HTTP Reverse Proxy Server. For development purposes `flask` built-in WSGI HTTP Server is used. |
| 142 | + |
| 143 | +`flask` uses `http://localhost:8000`, `gunicorn` uses `unix:/tmp/nginx-gunicorn.socket`, `nginx` uses `http://localhost:80`. Make sure these addresses is free for usage, or change specific server configuration. |
| 144 | + |
| 145 | +`nginx` will not start until `gunicorn` creates `/tmp/gunicorn-ready` file. Make sure you have access to create this file. |
| 146 | + |
| 147 | +Open terminal and move in project root. Run `./scripts/wsgi/<environment>.sh <server>` where `<environment>` is either `prodction`, `development` or `testing`, and `<server>` is either `flask`, `gunicorn` or `nginx`. Example: `./scripts/wsgi/production.sh gunicorn`. |
| 148 | + |
| 149 | +Usually you will want to run both `gunicorn` and `nginx`. To do so run scripts in separate terminals (recommend way). After that visit `nginx` address. |
| 150 | + |
| 151 | +Run `./scripts/server/stop_nginx.sh` in order to stop nginx. |
| 152 | + |
| 153 | +nginx uses simple configuration from `./src/configs/nginx.conf`. You can ignore this and use any configuration for nginx that is appropriate to you. However, it is recommend to use exact configuration as in current version for `flask` and `gunicorn`. Instead, make PR if you think that something is wrong with these two configurations. |
| 154 | + |
| 155 | +### Database |
| 156 | + |
| 157 | +In both development and testing environments `SQLite` is used. For production `PostgreSQL` is recommended, but you can use any of [supported databases](https://docs.sqlalchemy.org/en/13/core/engines.html#supported-databases). App already configured for both `SQLite` and `PostgreSQL`, for another databases you may have to install additional Python packages. |
| 158 | + |
| 159 | +Development and testing databases will be located at `src/development.sqlite` and `src/testing.sqlite` respectively. |
| 160 | + |
| 161 | + |
| 162 | +## Deployment |
| 163 | + |
| 164 | +Regardless of any platform you choose for hosting, it is recommend to manually configure number of workers, number of workers connections and number of threads for both `gunicorn` and `nginx`. |
| 165 | + |
| 166 | +### Heroku |
| 167 | + |
| 168 | +1. If you don't have [Heroku](https://heroku.com/) installed, then it is a time to do that. |
| 169 | + |
| 170 | +2. If you don't have Heroku remote, then add it: |
| 171 | +- for existing app: |
| 172 | +```git |
| 173 | +git remote add heroku <URL> |
| 174 | +``` |
| 175 | +- for new app: |
| 176 | +``` |
| 177 | +heroku create |
| 178 | +``` |
| 179 | + |
| 180 | +3. We need both python and nginx build packs. Python build pack should be added automatically, but we will do it manually. For nginx build pack you can use whatever you want: [official one](https://github.com/heroku/heroku-buildpack-nginx), [my own one](https://github.com/Amaimersion/heroku-buildpack-nginx-for-yandex-disk-telegram-bot) or create your own one. In case of not using my own nginx build pack don't forget about compatibility (config paths, environment variables names, etc.). |
| 181 | +``` |
| 182 | +heroku buildpacks:set heroku/python |
| 183 | +heroku buildpacks:add https://github.com/Amaimersion/heroku-buildpack-nginx-for-yandex-disk-telegram-bot.git |
| 184 | +``` |
| 185 | + |
| 186 | +4. We need Heroku `PostgreSQL` addon in order to use that database. |
| 187 | + |
| 188 | +``` |
| 189 | +heroku addons:create heroku-postgresql:hobby-dev |
| 190 | +``` |
| 191 | + |
| 192 | +Later you can view the DB content by using `heroku pg:psql`. |
| 193 | + |
| 194 | +5. Switch to new branch special for Heroku (don't ever push it!): |
| 195 | +```git |
| 196 | +git checkout -b heroku |
| 197 | +``` |
| 198 | + |
| 199 | +6. Make sure `.env` file is created and filled. Remove it from `.gitignore`. Don't forget: don't ever push it anywhere but Heroku. |
| 200 | + |
| 201 | +7. Add changes for pushing to Heroku: |
| 202 | +- if you edited files on heroku branch: |
| 203 | +```git |
| 204 | +git add . |
| 205 | +git commit -m <message> |
| 206 | +``` |
| 207 | +- if you want push changes from another branch: |
| 208 | +```git |
| 209 | +git merge <another branch> -m <message> |
| 210 | +``` |
| 211 | + |
| 212 | +8. Upload files to Heroku: |
| 213 | +```git |
| 214 | +git push heroku heroku:master |
| 215 | +``` |
| 216 | + |
| 217 | +You should do № 7 and № 8 every time you want to push changes. |
| 218 | + |
| 219 | + |
| 220 | +## Contribution |
| 221 | + |
| 222 | +Feel free to use [issues](https://github.com/Amaimersion/yandex-disk-telegram-bot/issues/new). [Pull requests](https://github.com/Amaimersion/yandex-disk-telegram-bot/compare) are also always welcome! |
| 223 | + |
| 224 | + |
| 225 | +## License |
| 226 | + |
| 227 | +[MIT](https://github.com/Amaimersion/yandex-disk-telegram-bot/blob/master/LICENSE). |
0 commit comments