Updated README
This commit is contained in:
parent
dc774262f8
commit
a7e79eb254
GPG Key ID:
FA35CAB49DACD3B2
32
README.md
32
README.md
|
|
@ -1,11 +1,11 @@
|
|||
<h1 align="center">TelegramPoster</h1>
|
||||
|
||||
<p align="center">
|
||||
<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>
|
||||
<a href="https://git.end-play.xyz/profitroll/TelegramPoster/src/branch/master/LICENSE"><img alt="License: GPL" src="https://img.shields.io/badge/License-GPL-blue"></a>
|
||||
<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>
|
||||
</p>
|
||||
|
||||
> Шукаєш інструкцію українською? А вона [ось тут](https://git.end-play.xyz/profitroll/TelegramPoster/src/branch/dev/README_uk.md) знаходиться)
|
||||
> Шукаєш інструкцію українською? А вона [ось тут](https://git.end-play.xyz/profitroll/TelegramPoster/src/branch/master/README_uk.md) знаходиться)
|
||||
|
||||
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 ;)
|
||||
|
||||
|
|
@ -21,7 +21,7 @@ Please note that Photos API also requires MongoDB so it makes sense to install a
|
|||
|
||||
## Installation
|
||||
|
||||
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.
|
||||
To make this bot run at first you need to have a Python interpreter, Photos API, MongoDB and optionally git (if you want to update using `git pull`). You can also ignore git and simply download source code, should also work fine. After that you're ready to go.
|
||||
|
||||
> 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
|
||||
|
|
@ -29,7 +29,7 @@ To make this bot run at first you need to have a Python interpreter, Photos API,
|
|||
> If it's non-standard executable path - you should also change
|
||||
> it in scripts you will use (`loop.sh`, `loop.bat`, `start.sh` and `start.bat`).
|
||||
|
||||
1. Install Mongo and Photos API:
|
||||
1. Install MongoDB and Photos API:
|
||||
|
||||
1. Install MongoDB by following [official installation manual](https://www.mongodb.com/docs/manual/installation)
|
||||
2. Install Photos API by following [Photos API's README](https://git.end-play.xyz/profitroll/PhotosAPI/src/branch/master/README.md)
|
||||
|
|
@ -42,19 +42,19 @@ To make this bot run at first you need to have a Python interpreter, Photos API,
|
|||
3. Create virtual environment [Optional]:
|
||||
|
||||
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.
|
||||
2. Create venv: `python -m venv .venv`
|
||||
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:
|
||||
|
||||
`python -m pip install -r requirements.txt`
|
||||
Without installing those - bot cannot work at all.
|
||||
|
||||
5. Configure "bot" and "owner" with your favorite text editor:
|
||||
5. Configure required keys with your favorite text editor:
|
||||
|
||||
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 `"bot.owner"`, `"reports.chat_id"`, `"bot.api_id"`, `"bot.api_hash"` and `"bot.bot_token"` keys' values.
|
||||
1. Copy config file: `cp config_example.json config.json`
|
||||
2. Open `config.json` using your favorite text editor. For example `nano config.json`, but you can also edit it with vim, mcedit, or Notepad/Notepad++ on Windows
|
||||
3. Change `"bot.owner"`, `"bot.api_id"`, `"bot.api_hash"` and `"bot.bot_token"` keys' values.
|
||||
|
||||
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).
|
||||
|
||||
|
|
@ -66,26 +66,26 @@ To make this bot run at first you need to have a Python interpreter, Photos API,
|
|||
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).
|
||||
|
||||
2. Configure Photos API:
|
||||
1. Change `"posting.api.address"` to the one your API servers uses
|
||||
1. Change `"posting.api.address"` and `"posting.api.address_external"` to the ones your API server uses
|
||||
2. Run your bot using `python main.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.
|
||||
|
||||
7. Add bot to the channel:
|
||||
|
||||
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 and `"posting.comments"` to comments group's ID.
|
||||
To use your bot of course you need to have a channel or group otherwise it 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 and `"posting.comments"` to comments group's ID.
|
||||
|
||||
8. Configure posting time:
|
||||
|
||||
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`.
|
||||
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`.
|
||||
|
||||
9. Good to go, run it!
|
||||
|
||||
Make sure MongoDB and Photos API are running and use `python main.py` to start it.
|
||||
Make sure MongoDB and Photos API are running and use `python main.py` to start the bot.
|
||||
Or you can also use `.\start.bat` on Windows and `bash ./start.sh` on Linux.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Command line arguments
|
||||
## CLI arguments
|
||||
|
||||
Of course bot also has them. You can perform some actions with them.
|
||||
|
||||
|
|
@ -105,6 +105,6 @@ Examples:
|
|||
|
||||
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.
|
||||
|
||||
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"`.
|
||||
All localization files are located in the `locale`. 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 - edit `"locale"` parameter in the `config.json`.
|
||||
|
||||
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.
|
||||
|
|
|
|||
121
README_uk.md
121
README_uk.md
|
|
@ -5,67 +5,104 @@
|
|||
<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>
|
||||
</p>
|
||||
|
||||
## ⚠️ Українська версія README dev гілки ще не готова! Користуйтесь англійською! ⚠️
|
||||
Цей бот використовується для однієї-єдиної задачі - публікувати фотографії з мого особистого архіву. Ось його код, тож ви також можете запустити бота і погратися з ним самостійно. Тільки не очікуйте, що він буде ідеальним. Це не так. Але ви завжди можете його форкнути ;)
|
||||
|
||||
Цей бот використовується для однієї-єдиної задачі - розміщувати фотографії з мого особистого архіву. Ось його код, тож Ви також можете захостити бота самостійно та розважитися з ним. Тільки не очікуйте, що він ідеальним. Не буде. Але гей, Ви завжди можете його доробити під себе ;)
|
||||
## Залежності
|
||||
|
||||
## Установка
|
||||
* [Python 3.8+](https://www.python.org) (рекомендується 3.9+)
|
||||
* [MongoDB](https://www.mongodb.com)
|
||||
* [PhotosAPI](https://git.end-play.xyz/profitroll/PhotosAPI)
|
||||
|
||||
Для запуску цього бота спочатку потрібно мати інтерпретатор Python та встановлений git. Google — Ваш друг у пошуках. Ви також можете ігнорувати git і просто завантажити код, також має спрацювати добре. Після цього Ви готові до встановлення.
|
||||
Користуйтесь [інструкцією зі встановлення MongoDB](https://www.mongodb.com/docs/manual/installation) та [README Photos API](https://git.end-play.xyz/profitroll/PhotosAPI/src/branch/master/README.md).
|
||||
|
||||
> У цьому README я вважаю, що Ви використовуєте python за замовчуванням у своїй
|
||||
> системі і PATH Вашої системи містить його. Якщо Ваш python за замовчуванням
|
||||
> є `python3` або, наприклад, `/home/user/.local/bin/python3.9` - використовуйте його натомість.
|
||||
> Якщо це нестандартний шлях до виконуваного файлу - Вам також слід змінити
|
||||
> це у скриптах, які Ви використовуватимете (`loop.sh`, `loop.bat`, `start.sh` та `start.bat`).
|
||||
Зверніть увагу, що Photos API також потребує MongoDB, тому має сенс спочатку встановити й налаштувати Mongo.
|
||||
|
||||
1. Завантажте бота:
|
||||
1. `git clone https://git.end-play.xyz/profitroll/TelegramSender.git` (якщо хочете використовувати git)
|
||||
2. `cd ./TelegramSender`
|
||||
## Встановлення
|
||||
|
||||
2. Встановіть залежності:
|
||||
`python -m pip install -r requirements.txt`
|
||||
Без їх установки бот не зможе працювати взагалі
|
||||
Щоб запустити бота, вам потрібно мати інтерпретатор Python, Photos API, MongoDB і, за бажанням, git (якщо ви хочете оновлювати за допомогою `git pull`). Ви також можете проігнорувати git і просто завантажити вихідний код, це також повинно спрацювати. Після цього ви готові до роботи.
|
||||
|
||||
3. Встановіть додаткові залежності [Не обов'язково]:
|
||||
`python -m pip install -r requirements-optional.txt`
|
||||
Вони не є обов’язковими, але можуть прискорити роботу бота
|
||||
> У цьому README я припускаю, що ви використовуєте python за замовчуванням у вашій
|
||||
> системі, і він міститься у вашому системному PATH. Якщо ваш python за замовчуванням
|
||||
> це `python3` або, наприклад, `/home/user/.local/bin/python3.9` - використовуйте його.
|
||||
> Якщо це нестандартний шлях до виконуваного файлу - вам також слід змінити
|
||||
> його у скриптах, які ви будете використовувати (`loop.sh`, `loop.bat`, `start.sh` та `start.bat`).
|
||||
|
||||
4. Налаштуйте свого бота за допомогою текстового редактора:
|
||||
`nano config.json`
|
||||
Ви можете редагувати за допомогою vim, nano, у Windows це Notepad або Notepad++. На Ваш смак.
|
||||
Якщо Ви не знаєте, де знайти bot_token і свій ідентифікатор, тут Ви можете знайти кілька підказок: [отримати токен бота](https://www.siteguarding.com/en/how-to-get-telegram-bot-api-token), [отримати свій ідентифікатор](https://www.alphr.com/telegram-find-user-id/), [отримати api_hash і api_id](https://core.telegram.org/api/obtaining_api_id).
|
||||
Також не забудьте змінити режим роботи бота. Ключ `"mode"` має в собі ключі `"post"` та `"submit"`, кожен з який може бути `true` або `false`.
|
||||
1. Встановіть MongoDB та Photos API:
|
||||
|
||||
5. Додайте бота на канал:
|
||||
Звичайно, щоб використовувати свого бота, Вам потрібно мати канал або групу, інакше немає сенсу мати такого бота. [Тут](https://stackoverflow.com/a/33497769) Ви можете знайти короткий гайд, як додати свого бота до каналу.
|
||||
1. Встановіть MongoDB, дотримуючись [офіційного посібника зі встановлення](https://www.mongodb.com/docs/manual/installation)
|
||||
2. Встановіть Photos API, дотримуючись [README Photos API](https://git.end-play.xyz/profitroll/PhotosAPI/src/branch/master/README.md)
|
||||
|
||||
6. Заповніть папку вмістом:
|
||||
Звичайно, бот не може опублікувати щось із нічого. Налаштуйте свій `config.json`, які медіа-типи бот повинен публікувати (`"posting", "extensions"`), коли їх публікувати (`"posting", "time"`), а також де їх знайти (`"locations"`). Ви також можете переміщати їх після надсилання, встановивши для `"posting", "move_sent"` значення `true`.
|
||||
2. Завантажте бота:
|
||||
|
||||
6. Готово, запускайте!
|
||||
`python ./main.py`
|
||||
Або ви також можете використовувати `.\start.bat` на Windows і `bash ./start.sh` на Linux.
|
||||
Крім того, доступні `loop.sh` і `loop.bat`, якщо ви хочете, щоб ваш бот запускався знову після зупинки або після використання команди `/reboot`.
|
||||
1. `git clone https://git.end-play.xyz/profitroll/TelegramPoster.git` (якщо ви використовуєте git)
|
||||
2. `cd TelegramPoster`
|
||||
|
||||
## Аргументи командного рядка
|
||||
3. Створіть віртуальне середовище [Необов'язково]:
|
||||
|
||||
Звичайно, у бота вони також є. З ними можна виконувати деякі дії.
|
||||
1. Встановіть модуль virtualenv: `pip install virtualenv`
|
||||
2. Створіть venv: `python -m venv .venv`
|
||||
3. Активуйте його за допомогою `ource .venv/bin/activate` в Linux, `.venv\Scripts\activate.bat` в CMD або `.venv\Scripts\Activate.ps1` в PowerShell.
|
||||
|
||||
* `--move-sent` - дозволяє перемістити всі надіслані файли з черги до папки надісланих
|
||||
* `--cleanup` - очистити файли в папках `queue` і `sent`, якщо вони вже надіслані. Потрібен аргумент `--confirm`
|
||||
* `--cleanup-index` - видалити всі надіслані записи з індексу. Потрібен аргумент `--confirm`
|
||||
* `--norun` - дозволяє виконувати наведені вище аргументи, не запускаючи самого бота
|
||||
4. Встановіть залежності проекту:
|
||||
|
||||
`python -m pip install -r requirements.txt`.
|
||||
Без їх встановлення бот не зможе працювати взагалі.
|
||||
|
||||
5. Налаштуйте необхідні ключі за допомогою вашого улюбленого текстового редактора:
|
||||
|
||||
1. Скопіюйте конфігураційний файл: `cp config_example.json config.json`
|
||||
2. Відкрийте `config.json` за допомогою вашого улюбленого текстового редактора. Наприклад, `nano config.json`, але ви також можете відредагувати його за допомогою vim, mcedit або Notepad/Notepad++ на Windows
|
||||
3. Змініть значення ключів `"bot.owner"`, `"bot.api_id"`, `"bot.api_hash"` і `"bot.bot_token"`.
|
||||
|
||||
Якщо ви не знаєте, де знайти bot_token і ваш id - тут ви можете знайти кілька підказок: [отримати токен бота](https://www.siteguarding.com/en/how-to-get-telegram-bot-api-token), [отримати свій id](https://www.alphr.com/telegram-find-user-id), [отримати api_hash та api_id](https://core.telegram.org/api/obtaining_api_id).
|
||||
|
||||
6. Налаштування бази даних та API:
|
||||
|
||||
1. Налаштуйте базу даних:
|
||||
1. Змініть хост і порт бази даних у ключах `"database.host"` і `"database.port"`. Для локальної установки за замовчуванням це будуть `127.0.0.1` і `27017` відповідно
|
||||
2. Змініть ім'я бази даних в `"database.name"`. Вона буде автоматично створена при запуску
|
||||
3. Якщо ви змінили користувача та пароль для доступу до бази даних, вам також слід змінити ключі `"database.user"` та `"database.password"`, інакше залиште їх `null` (за замовчуванням).
|
||||
|
||||
2. Налаштуйте Photos API:
|
||||
1. Змініть `"posting.api.address"` та `"posting.api.address_external"` на ті, що використовує ваш сервер API
|
||||
2. Запустіть бота за допомогою `python main.py --create-user --create-album`, щоб налаштувати нового користувача та альбом. Ви також можете скористатися ручним створенням користувача і альбому, описаним [у вікі](https://git.end-play.xyz/profitroll/TelegramPoster/wiki/Configuring-API). Ви також можете змінити ім'я користувача, пароль і альбом у `"posting.api"` на користувача і альбом, які у вас є, якщо у вас вже налаштовані альбом і користувач Photos API. У цьому випадку вам не потрібно створювати нові.
|
||||
|
||||
7. Додайте бота до каналу:
|
||||
|
||||
Щоб використовувати бота, вам, звичайно, потрібно мати канал або групу, інакше немає сенсу мати такого бота. [Тут](https://stackoverflow.com/a/33497769) ви можете знайти короткий посібник, як додати бота до каналу. Після цього просто встановіть `"posting.channel"` на ID вашого каналу і `"posting.comments"` на ID групи коментарів.
|
||||
|
||||
8. Налаштуйте час публікації:
|
||||
|
||||
Щоб ваш бот публікував випадковий контент, вам потрібно налаштувати `"posting.time"` зі списком рядків у форматі "ДД:ММ" або використовувати `"posting.interval"` у форматі "XdXhXmXs". Щоб використовувати інтервал замість вибраного часу, встановіть `"posting.use_interval"` у значення `true`.
|
||||
|
||||
9. Готово, запускайте!
|
||||
|
||||
Переконайтеся, що MongoDB і Photos API запущені і використовуйте `python main.py` для запуску бота.
|
||||
Або ви також можете використовувати `.\start.bat` в Windows і `bash ./start.sh` в Linux.
|
||||
Додатково доступні `loop.sh` і `loop.bat`, якщо ви хочете, щоб ваш бот запустився знову після зупинки або після використання команди `/shutdown`.
|
||||
|
||||
Якщо вам потрібні додаткові інструкції щодо налаштування бота або у вас виникли труднощі - скористайтеся [вікі в цьому репозиторії](https://git.end-play.xyz/profitroll/TelegramPoster/wiki), щоб отримати детальніші інструкції.
|
||||
|
||||
## CLI аргументи
|
||||
|
||||
Звичайно, бот також має CLI аргументи. За допомогою них можна виконувати деякі дії.
|
||||
|
||||
* `--create-user` - створити нового користувача API. Потребує встановленого конфігураційного ключа `"posting.api.address"`;
|
||||
* `--create-album` - створити новий альбом API. Вимагає заповнених адреси API та конфігурації користувача (`"posting.api"`).
|
||||
|
||||
Приклади:
|
||||
|
||||
* `python3 ./main.py --move-sent --norun`
|
||||
* `python3 ./main.py --cleanup --confirm`
|
||||
* `python main.py --create-user`
|
||||
* `python main.py --create-user --create-album`
|
||||
|
||||
## Поради та покращення
|
||||
|
||||
* Можливо, ви захочете налаштувати бота для роботи як системну службу. У вікі є [сторінка з цього питання](https://git.end-play.xyz/profitroll/TelegramPoster/wiki/Configuring-Service).
|
||||
|
||||
## Локалізація
|
||||
|
||||
Бот може використовувати різні мови. Є деякі попередньо встановлені (Англійська та Українська), однак Ви можете додавати свої власні локалізації теж.
|
||||
Бот може використовувати файли локалізації. Деякі з них встановлено за замовчуванням (англійська та українська), але ви також можете додавати свої власні.
|
||||
|
||||
Всі файли локалізації знаходяться у папці `locale`, якщо в конфігураційному файлі не вказано іншу. Просто скопіюйте цікавлячий Вас файл, назвіть його відповідно до [тегів мови IETF](https://en.wikipedia.org/wiki/IETF_language_tag) (якщо Ви хочете, щоб переклад був сумісним з перекладами Telegram) або просто вкажіть свою власну назву. Збережіть свій переклад як json файл і все готово. Якщо ви хочете змінити мову за замовчуванням для повідомлень самого бота, які не можуть визначити мову адміністратора, відредагуйте параметр `"locale"` у `config.json`. Якщо ця мова недоступна, замість неї буде використано `"locale_fallback"`. Якщо обидві мови недоступні - буде показано помилку. Для зміни мови виведення консолі та логування вам слід відредагувати `"locale_log"`.
|
||||
Усі файли локалізації знаходяться у теці `locale`. Просто скопіюйте файл локалі за вашим вибором, назвіть його відповідно до [мовних кодів IETF](https://en.wikipedia.org/wiki/IETF_language_tag) (якщо ви хочете, щоб ваша локаль була сумісна з локалями Telegram) або дайте йому власну назву. Збережіть переклад у форматі json, і все буде готово. Якщо ви хочете змінити локаль за замовчуванням для повідомлень - відредагуйте параметр `"locale"` у файлі `config.json`.
|
||||
|
||||
Ми рекомендуємо вносити будь-які зміни лише до вашої окремої мови. Або, принаймні, завжди мати резервну копію, наприклад, `en.json` як запасний варіант.
|
||||
Ми рекомендуємо вносити зміни лише у вашу власну локаль. Або, принаймні, завжди мати резервну копію, наприклад, `en.json` як запасний варіант.
|
||||
|
|
|
|||
Loading…
Reference in New Issue