kopia lustrzana https://github.com/J-Rios/TLG_JoinCaptchaBot
Better README
James Glenn
Jose
rodzic
196887c735
commit
645b63411b
267
README.md
267
README.md
|
|
@ -1,100 +1,109 @@
|
|||
# TLG_JoinCaptchaBot
|
||||
[](https://github.com/J-Rios/TLG_JoinCaptchaBot/blob/master/LICENSE) [](https://github.com/J-Rios/TLG_JoinCaptchaBot/stargazers) [](https://github.com/J-Rios/TLG_JoinCaptchaBot/network/members) [](https://github.com/J-Rios/TLG_JoinCaptchaBot/issues) [](https://www.python.org/) [](https://t.me/join_captcha_bot) [](https://github.com/J-Rios/TLG_JoinCaptchaBot/graphs/commit-activity) [](https://github.com/J-Rios/TLG_JoinCaptchaBot/commits/master) [](https://makeapullrequest.com)
|
||||
|
||||
<p align="center">
|
||||
<img width="100%" height="100%" src="https://gist.githubusercontent.com/J-Rios/05d7a8fc04166fa19f31a9608033d10b/raw/32dee32a530c0a0994736fe2d02a1747478bd0e3/captchas.png">
|
||||
</p>
|
||||
|
||||
Telegram Bot to verify if a new member joining a group is a human.
|
||||
Upon a new user join a group, the Bot send an image-based [captcha challenge](https://en.wikipedia.org/wiki/CAPTCHA) that must be solved to allow the user stay in the group. If the new user fails to solve the captcha within a set time limit, they are removed from the group. Additionally, any message from a new user that includes a URL prior to the completion of the captcha will be considered Spam and will be deleted.
|
||||
## Overview
|
||||
|
||||
## Donate
|
||||
TLG_JoinCaptchaBot is a Telegram Bot designed to verify that new members joining a group are humans by presenting an image-based [CAPTCHA challenge](https://en.wikipedia.org/wiki/CAPTCHA). The bot:
|
||||
|
||||
Do you like this Bot? Buy me a coffee :)
|
||||
- Automatically sends a CAPTCHA when a new user joins
|
||||
- Removes users who fail to solve the CAPTCHA within a specified time limit
|
||||
- Deletes messages containing URLs sent by users who haven't completed the CAPTCHA (anti-spam)
|
||||
|
||||
Paypal:
|
||||
## Table of Contents
|
||||
|
||||
[https://www.paypal.me/josrios](https://www.paypal.me/josrios)
|
||||
- [Requirements](#requirements)
|
||||
- [Installation](#installation)
|
||||
- [Configuration](#configuration)
|
||||
- [Usage](#usage)
|
||||
- [Deployment](#deployment)
|
||||
- [Systemd Service](#systemd-service)
|
||||
- [Docker](#docker)
|
||||
- [Advanced Features](#advanced-features)
|
||||
- [Bot Owner Commands](#bot-owner)
|
||||
- [Private Mode](#make-bot-private)
|
||||
- [Scalability (Polling vs Webhook)](#scalability-polling-or-webhook)
|
||||
- [Localization](#adding-a-new-language)
|
||||
- [Languages Contributors](#languages-contributors)
|
||||
- [Support Development](#donate)
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.6+
|
||||
- Pillow and its prerequisites
|
||||
- Telegram Bot Token (from [@BotFather](https://t.me/BotFather))
|
||||
|
||||
## Installation
|
||||
|
||||
Note: Use Python 3.6 or above to install and run the Bot, previous python version are unsupported.
|
||||
### 1. Install Pillow prerequisites
|
||||
|
||||
To generate Captchas, the Bot uses [multicolor_captcha_generator library](https://github.com/J-Rios/multicolor_captcha_generator), which uses Pillow to generate the images.
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y make libtiff5-dev libjpeg62-turbo-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk
|
||||
```
|
||||
|
||||
1. Install Pillow prerequisites:
|
||||
### 2. Install Python3 and tools
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y make libtiff5-dev libjpeg62-turbo-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk
|
||||
```
|
||||
```bash
|
||||
sudo apt-get install python3 python3-pip python3-venv
|
||||
```
|
||||
|
||||
2. Install Python3 and their tools:
|
||||
### 3. Get and setup the project
|
||||
|
||||
```bash
|
||||
sudo apt-get install python3 python3-pip python3-venv
|
||||
```
|
||||
```bash
|
||||
git clone https://github.com/J-Rios/TLG_JoinCaptchaBot
|
||||
cd TLG_JoinCaptchaBot
|
||||
make setup
|
||||
```
|
||||
|
||||
3. Get and setup the project:
|
||||
### 4. Configure your Telegram Bot token
|
||||
|
||||
```bash
|
||||
git clone https://github.com/J-Rios/TLG_JoinCaptchaBot
|
||||
cd TLG_JoinCaptchaBot
|
||||
make setup
|
||||
```
|
||||
Edit the `src/settings.py` file:
|
||||
|
||||
4. Set Telegram Bot account Token (get it from @BotFather) in "src/settings.py" file:
|
||||
|
||||
```python
|
||||
'TOKEN' : 'XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
|
||||
```
|
||||
```python
|
||||
'TOKEN' : 'XXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
All Bot configurations can be done easily by modifying them in the **"src/settings.json"** file.
|
||||
|
||||
For more experienced users, you can use environment variables to setup all that properties (this is really useful for advance deployment when using [Virtual Environments](https://docs.python.org/3/tutorial/venv.html) and/or [Docker](https://docs.docker.com/get-started/) to isolate the Bot process execution).
|
||||
Configuration is handled through the `src/settings.json` file. Advanced users can also use environment variables, which is useful for deployment scenarios with [virtual environments](https://docs.python.org/3/tutorial/venv.html) or [Docker](https://docs.docker.com/get-started/).
|
||||
|
||||
## Usage
|
||||
|
||||
To ease it usage in Linux, a **Makefile** is provided.
|
||||
|
||||
- Check usage help information:
|
||||
|
||||
```bash
|
||||
make
|
||||
```
|
||||
|
||||
- Launch the Bot:
|
||||
|
||||
```bash
|
||||
make start
|
||||
```
|
||||
|
||||
- Check if the Bot is running:
|
||||
|
||||
```bash
|
||||
make status
|
||||
```
|
||||
|
||||
- Stop the Bot:
|
||||
|
||||
```bash
|
||||
make stop
|
||||
```
|
||||
|
||||
## Systemd service
|
||||
|
||||
For systemd based systems, you can setup the Bot as daemon service.
|
||||
|
||||
To do that, you need to create a new service description file for the Bot as follow:
|
||||
A `Makefile` is provided for convenient operation:
|
||||
|
||||
```bash
|
||||
[vim or nano] /etc/systemd/system/tlg_joincaptcha_bot.service
|
||||
# View available commands
|
||||
make
|
||||
|
||||
# Start the bot
|
||||
make start
|
||||
|
||||
# Check bot status
|
||||
make status
|
||||
|
||||
# Stop the bot
|
||||
make stop
|
||||
```
|
||||
|
||||
File content:
|
||||
## Deployment
|
||||
|
||||
### Systemd Service
|
||||
|
||||
To run the bot as a daemon service on systemd-based systems:
|
||||
|
||||
1. Create a service file:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/tlg_joincaptcha_bot.service
|
||||
```
|
||||
|
||||
2. Add the following content (adjust paths as needed):
|
||||
|
||||
```
|
||||
[Unit]
|
||||
Description=Telegram Join Captcha Bot Daemon
|
||||
Wants=network-online.target
|
||||
|
|
@ -110,156 +119,128 @@ ExecReload=/path/to/TLG_JoinCaptchaBot/tools/kill
|
|||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Then, to add the new service into systemd, you should enable it:
|
||||
3. Enable and start the service:
|
||||
|
||||
```bash
|
||||
systemctl enable --now tlg_joincaptcha_bot.service
|
||||
sudo systemctl enable --now tlg_joincaptcha_bot.service
|
||||
sudo systemctl start tlg_joincaptcha_bot.service
|
||||
```
|
||||
|
||||
Now, you can start the service (Bot) by:
|
||||
4. Check service status:
|
||||
|
||||
```bash
|
||||
systemctl start tlg_joincaptcha_bot.service
|
||||
sudo systemctl status tlg_joincaptcha_bot.service
|
||||
```
|
||||
|
||||
You can check if the service (Bot) is running by:
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
systemctl status tlg_joincaptcha_bot.service
|
||||
```
|
||||
Docker support is available for easy deployment and server migration. See the [Docker specific documentation](docker/README.md) for details on creating a Docker container for the bot.
|
||||
|
||||
Remember that, if you wan't to disable it, you should execute:
|
||||
## Advanced Features
|
||||
|
||||
```bash
|
||||
systemctl disable tlg_joincaptcha_bot.service
|
||||
```
|
||||
### Bot Owner
|
||||
|
||||
## Docker
|
||||
The bot owner can execute special commands:
|
||||
- `/allowgroup`: Add groups to the allowed list (when bot is private)
|
||||
- `/allowuserlist`: Exempt specific users from CAPTCHA verification (useful for accessibility needs)
|
||||
|
||||
You can also run the bot on [Docker](https://docs.docker.com/get-started/). This allows easy server migration and automates the installation and setup. Look at the [docker specific documentation](docker/README.md) for more details about how to create a Docker Container for Captcha Bot.
|
||||
|
||||
## Bot Owner
|
||||
|
||||
The **Bot Owner** can run special commands that no one else can use, like /allowgroup (if the Bot is private, this set allowed groups where the Bot can be used) or /allowuserlist (to make Bot don't ask for captcha to some users, useful for example for blind users).
|
||||
|
||||
You can setup a Bot Owner by specifying the Telegram User ID or Alias in "settings.py" file. For example:
|
||||
Set a bot owner in `settings.py`:
|
||||
|
||||
```python
|
||||
"BOT_OWNER": "@JoseTLG",
|
||||
"BOT_OWNER": "@YourUsername",
|
||||
```
|
||||
|
||||
## Make Bot Private
|
||||
### Make Bot Private
|
||||
|
||||
By default, the Bot is **Public**, so any Telegram user can add and use the Bot in any group, but you can set it to be **Private** so the Bot just can be used in allowed groups (Bot owner allows them with **/allow_group** command).
|
||||
By default, anyone can add the bot to any group. To restrict usage to specific groups:
|
||||
|
||||
You can set Bot to be Private in "settings.py" file:
|
||||
1. Set the bot to private mode in `settings.py`:
|
||||
|
||||
```python
|
||||
"BOT_PRIVATE" : True,
|
||||
"BOT_PRIVATE": True,
|
||||
```
|
||||
|
||||
**Note:** If you have a Public Bot and set it to Private, it will leave any group where is not allowed to be used when a new user joins.
|
||||
2. Use the `/allow_group` command to specify permitted groups.
|
||||
|
||||
**Note:** Telegram Private Groups could changes their chat ID when it become a public super-group, so the Bot will leave the group and the owner has to set the new group chat ID with /allow_group.
|
||||
**Note:** If a public group becomes a supergroup, the chat ID may change, requiring re-authorization.
|
||||
|
||||
## Scalability (Polling or Webhook)
|
||||
### Scalability (Polling or Webhook)
|
||||
|
||||
By default, Bot checks and receives updates from Telegram Servers by **Polling** (it periodically requests and gets from Telegram Server if there is any new updates in the Bot account corresponding to that Bot Token), this is really simple and can be used for low to median scale Bots. However, you can configure the Bot to use **Webhook** instead if you expect to handle a large number of users/groups (with webhook, the Telegram Server is the one that will connect to you machine and send updates to the Bot when there is any new update).
|
||||
#### Polling (Default)
|
||||
The bot periodically checks for updates from Telegram servers. This is suitable for small to medium deployments.
|
||||
|
||||
To use Webhook instead Polling, you need a signed certificate file in the system, you can create the key file and self-sign the cert through openssl tool:
|
||||
#### Webhook (For larger deployments)
|
||||
The bot receives updates directly from Telegram servers, which improves performance for high-traffic bots.
|
||||
|
||||
To configure webhook:
|
||||
|
||||
1. Generate SSL certificate:
|
||||
|
||||
```bash
|
||||
openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 3650 -out cert.pem
|
||||
```
|
||||
|
||||
Once you have the key and cert files, setup the next lines in "settings.py" file to point to expected host system address, port, path and certificate files:
|
||||
2. Configure webhook settings in `settings.py`:
|
||||
|
||||
```python
|
||||
"WEBHOOK_IP": "0.0.0.0",
|
||||
"WEBHOOK_PORT": 8443,
|
||||
"WEBHOOK_PATH": "/TLG_JoinCaptchaBot"
|
||||
"WEBHOOK_CERT" : SCRIPT_PATH + "/cert.pem",
|
||||
"WEBHOOK_CERT_PRIV_KEY" : SCRIPT_PATH + "/private.key",
|
||||
"WEBHOOK_PATH": "/TLG_JoinCaptchaBot",
|
||||
"WEBHOOK_CERT": SCRIPT_PATH + "/cert.pem",
|
||||
"WEBHOOK_CERT_PRIV_KEY": SCRIPT_PATH + "/private.key",
|
||||
```
|
||||
|
||||
(Optional) In case you want to use a reverse proxy between Telegram Server and the system that runs the Bot, you need to setup the Proxy Webhook URL setting:
|
||||
3. For reverse proxy setups (optional):
|
||||
|
||||
```python
|
||||
"WEBHOOK_URL": "https://example.com:8443/TLG_JoinCaptchaBot"
|
||||
```
|
||||
|
||||
Then, you need to change Bot connection mode from polling to webhook by setting to True the next configuration:
|
||||
4. Enable webhook mode:
|
||||
|
||||
```python
|
||||
"CAPTCHABOT_USE_WEBHOOK": True,
|
||||
```
|
||||
|
||||
To go back and use Polling instead Webhook, just set the config back to False:
|
||||
|
||||
```python
|
||||
"CAPTCHABOT_USE_WEBHOOK": False,
|
||||
```
|
||||
|
||||
## Adding a New Language
|
||||
|
||||
Actual language support is based on external JSON files that contain all bot texts for each language.
|
||||
The bot supports multiple languages through external JSON files. To add a new language:
|
||||
|
||||
To add support for a new language you must follow this steps:
|
||||
|
||||
1. Fork the project repository, clone it and create a new branch to work on it (i.e. named language-support-en).
|
||||
|
||||
2. Copy from one of the existing language JSON files from [here](https://github.com/J-Rios/TLG_JoinCaptchaBot/tree/master/src/language) to a new one.
|
||||
|
||||
3. Change the name of that file for the language ISO Code of the language that you want.
|
||||
|
||||
4. Translate each text from JSON key values of the file without breaking the JSON format/structure (it should be valid for JSON parsers) and maintaining JSON key names. Keep command names in english (i.e. don't translate "START", "HELP"... /start /help ...) and don't remove special characters (like {}, ", ', \n...) too!
|
||||
|
||||
5. Make a pull request of that branch with the new language file into this repository and wait for it to be accepted.
|
||||
|
||||
6. Then, I will make the integration into source code and actual Bot account (@join_captcha_bot).
|
||||
|
||||
7. Enjoy the new language :)
|
||||
1. Fork the repository and create a new branch (e.g., `language-support-xx`)
|
||||
2. Copy an existing language file from the [language directory](https://github.com/J-Rios/TLG_JoinCaptchaBot/tree/master/src/language)
|
||||
3. Rename the file to the ISO code of your target language
|
||||
4. Translate all text values while maintaining:
|
||||
- The JSON structure and key names
|
||||
- Command names in English (`START`, `HELP`, etc.)
|
||||
- Special characters (`{}`, `"`, `'`, `\n`, etc.)
|
||||
5. Submit a pull request with your translation
|
||||
|
||||
## Languages Contributors
|
||||
|
||||
- Arabic: [@damascene](https://github.com/damascene)
|
||||
|
||||
- Basque: [@xa2er](https://github.com/xa2er)
|
||||
|
||||
- Belarusian: [@antikruk](https://github.com/antikruk)
|
||||
|
||||
- Catalán: Adela Casals i Jorba
|
||||
|
||||
- Chinese (Mainland): [神林](https://github.com/jyxjjj)
|
||||
|
||||
- Esperanto: Pablo Busto & Porrumentzio.
|
||||
|
||||
- Esperanto: Pablo Busto & Porrumentzio
|
||||
- Finnish: [Aminda Suomalainen (@Mikaela)](https://github.com/Mikaela)
|
||||
|
||||
- French: [Mathieu H (@aurnytoraink)](https://github.com/Aurnytoraink)
|
||||
|
||||
- Galician: [Fernando Flores (Fer6Flores)](https://github.com/Fer6Flores); Iváns
|
||||
|
||||
- German: [@weerdenburg](https://github.com/weerdenburg), [@MossDerg](https://github.com/MossDerg)
|
||||
|
||||
- Indonesian: ForIndonesian
|
||||
|
||||
- Italian: Noquitt, [Nicola Davide (@nidamanx)](https://github.com/nidamanx)
|
||||
|
||||
- Kannada: [@itsAPK](https://github.com/itsAPK)
|
||||
|
||||
- Korean: [@dakeshi](https://github.com/dakeshi)
|
||||
|
||||
- Persian: [@m4hbod](https://github.com/M4hbod)
|
||||
|
||||
- Portuguese (Brazil): Anahuac de Paula Gil
|
||||
|
||||
- Russian: Unattributed (anonymous), [@stezkoy](https://github.com/Stezkoy), [Roman (@toxi22)](https://github.com/toxi22)
|
||||
|
||||
- Serbo-Croatian: [@IlijaDj](https://github.com/IlijaDj)
|
||||
|
||||
- Slovak: [@dumontiskooo](https://t.me/dumontiskooo)
|
||||
|
||||
- Ukrainian: Vadym Zhushman (@zhushman00), [Roman (@toxi22)](https://github.com/toxi22)
|
||||
|
||||
- Uzbek: [@mhwebuz](https://github.com/mhwebuz)
|
||||
|
||||
## Donate
|
||||
|
||||
If you find this bot useful, consider supporting the developer:
|
||||
|
||||
Paypal: [https://www.paypal.me/josrios](https://www.paypal.me/josrios)
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue