This repository has been archived on 2024-08-21. You can view files and clone it, but cannot push or open issues or pull requests.
TelegramPoster/README.md

116 lines
7.4 KiB
Markdown
Raw Normal View History

2023-03-09 17:16:38 +02:00
<h1 align="center">TelegramPoster</h1>
2023-03-09 12:48:50 +02:00
<p align="center">
2023-03-12 20:25:35 +02:00
<a href="https://git.end-play.xyz/profitroll/TelegramPoster/src/branch/dev/LICENSE"><img alt="License: GPL" src="https://img.shields.io/badge/License-GPL-blue"></a>
2023-03-09 12:48:50 +02:00
<a href="https://git.end-play.xyz/profitroll/TelegramPoster"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
2023-03-09 17:17:35 +02:00
</p>
2023-03-12 20:25:35 +02:00
> Шукаєш інструкцію українською? А вона [ось тут](https://git.end-play.xyz/profitroll/TelegramPoster/src/branch/dev/README_uk.md) знаходиться)
2022-08-12 11:12:41 +03:00
2022-08-10 14:08:15 +03:00
This bot is used for one and only task - post pictures from my personal archive. Here's its source code so you can also host a bot and have fun with it. Just don't exepect it to be brilliant. It is not. But hey, you can always fork it ;)
2022-08-09 12:46:15 +03:00
2023-03-12 20:25:35 +02:00
## Dependencies
2023-03-13 14:02:06 +02:00
* [Python 3.7+](https://www.python.org) (3.9+ recommended)
* [MongoDB](https://www.mongodb.com)
* [PhotosAPI](https://git.end-play.xyz/profitroll/PhotosAPI)
Use [MongoDB's installation manual](https://www.mongodb.com/docs/manual/installation) and [Photos API's README](https://git.end-play.xyz/profitroll/PhotosAPI/src/branch/master/README.md).
2023-03-12 20:25:35 +02:00
Please note that Photos API also requires MongoDB so it makes sense to install and configure Mongo first.
2022-08-09 12:46:15 +03:00
## Installation
2023-03-09 12:48:50 +02:00
2023-03-12 20:25:35 +02:00
To make this bot run at first you need to have a Python interpreter, Photos API, MongoDB and optionally git. You can also ignore git and simply download source code, should also work fine. After that you're ready to go.
2022-08-09 12:46:15 +03:00
2022-08-09 13:30:36 +03:00
> In this README I assume that you're using default python in your
> system and your system's PATH contains it. If your default python
> is `python3` or for example `/home/user/.local/bin/python3.9` - use it instead.
2023-03-12 20:25:35 +02:00
> If it's non-standard executable path - you should also change
2022-08-09 13:30:36 +03:00
> it in scripts you will use (`loop.sh`, `loop.bat`, `start.sh` and `start.bat`).
2023-03-12 20:25:35 +02:00
1. Install Mongo and Photos API:
2023-03-13 14:02:06 +02:00
2023-03-12 20:57:22 +02:00
1. Install MongoDB by following [official installation manual](https://www.mongodb.com/docs/manual/installation)
2023-03-12 20:25:35 +02:00
2. Install Photos API by following [Photos API's README](https://git.end-play.xyz/profitroll/PhotosAPI/src/branch/master/README.md)
2. Download the bot:
2023-03-13 14:02:06 +02:00
1. `git clone -b dev https://git.end-play.xyz/profitroll/TelegramPoster.git` (if you're using git)
2023-03-13 12:33:30 +02:00
2. `cd TelegramPoster`
2022-08-09 12:46:15 +03:00
2023-03-13 12:33:30 +02:00
3. Create virtual environment [Optional]:
2023-03-13 14:02:06 +02:00
2023-03-13 12:33:30 +02:00
1. Install virtualenv module: `pip install virtualenv`
2. Create venv: `python -m venv env`
3. Activate it using `source venv/bin/activate` on Linux, `venv\Scripts\activate.bat` in CMD or `venv\Scripts\Activate.ps1` in PowerShell.
4. Install project's dependencies:
2023-03-13 14:02:06 +02:00
2022-08-09 12:46:15 +03:00
`python -m pip install -r requirements.txt`
2023-03-13 12:33:30 +02:00
Without installing those - bot cannot work at all.
2022-08-09 12:46:15 +03:00
2023-03-13 12:33:30 +02:00
5. Install optional dependencies [Optional]:
2023-03-13 14:02:06 +02:00
2022-08-09 12:46:15 +03:00
`python -m pip install -r requirements-optional.txt`
2023-03-13 12:33:30 +02:00
These are not required but can make the bot run a bit faster.
2022-08-09 12:46:15 +03:00
2023-03-13 12:33:30 +02:00
6. Configure "bot" and "owner" with your favorite text editor:
2023-03-13 14:02:06 +02:00
1. Copy file `config_example.json` to `config.json`
2. Open `config.json` using your favorite text editor. For example `nano config.json`, but you can edit with vim, nano, on Windows it's Notepad or Notepad++. Whatever
3. Change `"owner"`, `"bot.api_id"`, `"bot.api_hash"` and `"bot.bot_token"` keys' values.
2023-03-12 20:57:22 +02:00
If you don't know where to find bot_token and your id - here you can find some hints: [get bot token](https://www.siteguarding.com/en/how-to-get-telegram-bot-api-token), [get your id](https://www.alphr.com/telegram-find-user-id), [get api_hash and api_id](https://core.telegram.org/api/obtaining_api_id).
2022-08-09 12:46:15 +03:00
2023-03-13 12:33:30 +02:00
7. Configure database and API:
2023-03-13 14:02:06 +02:00
2023-03-12 20:25:35 +02:00
1. Configure database:
2023-03-13 12:33:30 +02:00
1. Change database host and port in keys `"database.host"` and `"database.port"`. For default local installation those will be `127.0.0.1` and `27017` respectively
2. Change database name to the one you like in `"database.name"`. It will be automatically created on start
2023-03-12 23:23:02 +02:00
3. If you've changed user and password to access the db, you should also change `"database.user"` and `"database.password"` keys, otherwise leave them `null` (default).
2023-03-13 14:02:06 +02:00
2023-03-12 20:25:35 +02:00
2. Configure Photos API:
2023-03-13 12:33:30 +02:00
1. Change `"posting.api.address"` to the one your API servers uses
2. Run your bot using `python poster.py --create-user --create-album` to configure its new user and album. You can also use manual user and album creation described [in the wiki](https://git.end-play.xyz/profitroll/TelegramPoster/wiki/Configuring-API). You can also change username, password and album in`"posting.api"` to the user and album you have if you already have Photos API album and user set up. In that case you don't need to create a new one.
2023-03-12 20:25:35 +02:00
2023-03-13 12:33:30 +02:00
8. Add bot to the channel:
2023-03-13 14:02:06 +02:00
2023-03-12 20:25:35 +02:00
To use your bot of course you need to have a channel or group otherwise makes no sense to have such a bot. [Here](https://stackoverflow.com/a/33497769) you can find a quick guide how to add your bot to a channel. After that simply set `"posting.channel"` to your channel's ID.
2023-03-13 12:33:30 +02:00
9. Configure posting time:
2023-03-13 14:02:06 +02:00
2023-03-12 20:25:35 +02:00
To make your bot post random content you need to configure `"posting.time"` with a list of "DD:MM" formatted strings or use `"posting.interval"` formatted as "XdXhXmXs". To use interval instead of selected time set `"posting.use_interval"` to `true`.
2023-03-13 12:33:30 +02:00
10. Good to go, run it!
2023-03-13 14:02:06 +02:00
2023-03-13 12:33:30 +02:00
Make sure MongoDB and Photos API are running and use `python poster.py` to start it.
2022-08-09 13:30:36 +03:00
Or you can also use `.\start.bat` on Windows and `bash ./start.sh` on Linux.
2023-03-20 14:55:55 +02:00
Additionally there are `loop.sh` and `loop.bat` available if you want your bot to start again after being stopped or after using `/shutdown` command.
2023-03-12 23:29:53 +02:00
2023-03-12 23:30:35 +02:00
If you need any further instructions on how to configure your bot or you had any difficulties doing so - please use [wiki in this repository](https://git.end-play.xyz/profitroll/TelegramPoster/wiki) to get more detailed instructions.
2023-03-12 20:57:22 +02:00
2022-08-09 12:46:15 +03:00
## Command line arguments
2023-03-09 12:48:50 +02:00
2022-08-09 12:46:15 +03:00
Of course bot also has them. You can perform some actions with them.
2023-03-09 12:48:50 +02:00
2023-03-12 23:23:02 +02:00
* `--create-user` - create new API user. Requires config key `"posting.api.address"` to be set;
* `--create-album` - create new API album. Requires API address and user config (`"posting.api"`) to be complete.
2022-08-09 12:46:15 +03:00
Examples:
2023-03-09 12:48:50 +02:00
2023-03-13 12:33:30 +02:00
* `python poster.py --create-user`
* `python poster.py --create-user --create-album`
2022-08-12 11:12:41 +03:00
2023-03-12 23:30:35 +02:00
## Tips and improvements
2023-03-13 12:33:30 +02:00
* You may want to configure your bot to work as a systemd service instead. There's [a tutorial for that](https://git.end-play.xyz/profitroll/TelegramPoster/wiki/Configuring-Service) in the wiki.
2023-03-12 23:30:35 +02:00
2022-08-12 11:12:41 +03:00
## Localization
2023-03-09 12:48:50 +02:00
2022-08-12 11:12:41 +03:00
Bot is capable of using custom locales. There are some that are pre-installed (English and Ukrainian), however you can add your own locales too.
2022-09-18 19:13:40 +03:00
All localization files are located in the `locale` folder, otherwise in folder specified in config file. Just copy locale file of your choice, name it in accordance to [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) (if you want your locale to be compatible with Telegram's locales) or define your own name. Save it as json and you're good to go. If you want to change default locale for messages, that cannot determine admin's locale - edit `"locale"` parameter in the `config.json`. If this locale is not available - `"locale_fallback"` will be used instead. If both are not available - error will be shown. For console output and logging locale you should edit `"locale_log"`.
2022-08-12 11:12:41 +03:00
2023-03-09 12:48:50 +02:00
We recommend to only make changes to your custom locale. Or at least always have your backup of for example `en.json` as your fallback.