Nikolay Tatarinov
57c24a79af
- Added ALLOWED_USERNAMES and ADMIN_USERNAMES to .env.example for user access control. - Implemented validation of Telegram Web App initData in a new telegram_auth.py module. - Enhanced API to check user access before fetching duties. - Updated README with instructions for configuring miniapp access. - Modified .dockerignore and .gitignore to include data directory and database files.
71 lines
2.3 KiB
Markdown
71 lines
2.3 KiB
Markdown
# Duty Teller (Telegram Bot)
|
||
|
||
A minimal Telegram bot boilerplate using [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) v22 with the `Application` API.
|
||
|
||
## Get a bot token
|
||
|
||
1. Open Telegram and search for [@BotFather](https://t.me/BotFather).
|
||
2. Send `/newbot` and follow the prompts to create a bot.
|
||
3. Copy the token BotFather gives you.
|
||
|
||
## Setup
|
||
|
||
1. **Clone and enter the project**
|
||
```bash
|
||
cd duty-teller
|
||
```
|
||
|
||
2. **Create a virtual environment (recommended)**
|
||
```bash
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/macOS
|
||
# or: venv\Scripts\activate # Windows
|
||
```
|
||
|
||
3. **Install dependencies**
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
4. **Configure the bot**
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
Edit `.env` and set `BOT_TOKEN` to the token from BotFather.
|
||
|
||
5. **Miniapp access (calendar)**
|
||
To allow access to the calendar miniapp, set `ALLOWED_USERNAMES` to a comma-separated list of Telegram usernames (without `@`). Users in `ADMIN_USERNAMES` also have access; the admin role is reserved for future bot commands and API features. If both are empty, no one can open the calendar.
|
||
|
||
## Run
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
The bot runs in polling mode. Send `/start` or `/help` to your bot in Telegram to test.
|
||
|
||
## Run with Docker
|
||
|
||
Ensure `.env` exists (e.g. `cp .env.example .env`) and contains `BOT_TOKEN`.
|
||
|
||
- **Dev** (volume mount; code changes apply without rebuild):
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up --build
|
||
```
|
||
Stop with `Ctrl+C` or `docker compose -f docker-compose.dev.yml down`.
|
||
|
||
- **Prod** (no volume; runs the built image; restarts on failure):
|
||
```bash
|
||
docker compose -f docker-compose.prod.yml up -d --build
|
||
```
|
||
For production deployments you may use Docker secrets or your orchestrator’s env instead of a `.env` file.
|
||
|
||
## Project layout
|
||
|
||
- `main.py` – Builds the `Application`, registers handlers, runs polling.
|
||
- `config.py` – Loads `BOT_TOKEN`, `ALLOWED_USERNAMES`, `ADMIN_USERNAMES` from env; exits if `BOT_TOKEN` is missing.
|
||
- `handlers/` – Command and error handlers; add new handlers here.
|
||
- `requirements.txt` – Pinned dependencies (PTB with job-queue, python-dotenv).
|
||
|
||
To add commands, define async handlers in `handlers/commands.py` (or a new module) and register them in `handlers/__init__.py`.
|