Nikolay Tatarinov
4824450088
- Introduced a new roles table in the database to manage user roles ('user' and 'admin') for access control.
- Updated the user model to include a foreign key reference to the roles table, allowing for role assignment.
- Enhanced command handlers to support the `/set_role` command for admins to assign roles to users.
- Refactored access control logic to utilize role checks instead of username/phone allowlists, improving security and maintainability.
- Updated documentation to reflect changes in access control mechanisms and role management.
- Added unit tests to ensure correct functionality of role assignment and access checks.
4.2 KiB
Configuration reference
All configuration is read from the environment (e.g. .env via python-dotenv). Source of truth: duty_teller/config.py and Settings.from_env().
| Variable | Type / format | Default | Description |
|---|---|---|---|
| BOT_TOKEN | string | (empty) | Telegram bot token from @BotFather. Required for the bot to run; if unset, the entry point exits with a clear message. The server that serves the Mini App API must use the same token as the bot; otherwise initData validation returns hash_mismatch. |
| DATABASE_URL | string (SQLAlchemy URL) | sqlite:///data/duty_teller.db |
Database connection URL. Example: sqlite:///data/duty_teller.db. |
| MINI_APP_BASE_URL | string (URL, no trailing slash) | (empty) | Base URL of the miniapp (for documentation and CORS). Trailing slash is stripped. Example: https://your-domain.com/app. |
| HTTP_PORT | integer | 8080 |
Port for the HTTP server (FastAPI + static webapp). |
| ALLOWED_USERNAMES | comma-separated list | (empty) | Not used for access. Kept for reference only. Access to the miniapp is controlled by roles in the DB (assigned by an admin via /set_role). |
| ADMIN_USERNAMES | comma-separated list | (empty) | Telegram usernames treated as admin fallback when the user has no role in the DB. If a user has a role in the DB, only that role applies. Example: admin1,admin2. |
| ALLOWED_PHONES | comma-separated list | (empty) | Not used for access. Kept for reference only. |
| ADMIN_PHONES | comma-separated list | (empty) | Phones treated as admin fallback when the user has no role in the DB (user sets phone via /set_phone). Comparison uses digits only. Example: +7 999 123-45-67. |
| MINI_APP_SKIP_AUTH | 1, true, or yes |
(unset) | If set, /api/duties is allowed without Telegram initData (dev only; insecure). |
| INIT_DATA_MAX_AGE_SECONDS | integer | 0 |
Reject Telegram initData older than this many seconds. 0 = disabled. Example: 86400 for 24 hours. |
| CORS_ORIGINS | comma-separated list | * |
Allowed origins for CORS. Leave unset or set to * for allow-all. Example: https://your-domain.com. |
| EXTERNAL_CALENDAR_ICS_URL | string (URL) | (empty) | URL of a public ICS calendar (e.g. holidays). If set, those days are highlighted on the duty grid; users can tap "i" on a cell to see the event summary. Empty = no external calendar. |
| DUTY_DISPLAY_TZ | string (timezone name) | Europe/Moscow |
Timezone for the pinned duty message in groups. Example: Europe/Moscow, UTC. |
| DEFAULT_LANGUAGE | en or ru (normalized) |
en |
Default UI language when the user's Telegram language is unknown. Values starting with ru are normalized to ru, otherwise en. |
Roles and access
Access to the calendar miniapp and admin actions is determined by roles stored in the database (table roles, link users.role_id). Roles: user (miniapp access) and admin (miniapp + /import_duty_schedule, /set_role). An admin assigns roles with /set_role @username user|admin (or by replying to a message with /set_role user|admin). If a user has no role in the DB, they are treated as admin only if they are listed in ADMIN_USERNAMES or ADMIN_PHONES (env fallback). ALLOWED_USERNAMES and ALLOWED_PHONES are not used for access.
Quick setup
- Copy
.env.exampleto.env. - Set
BOT_TOKENto the token from BotFather. - Set
ADMIN_USERNAMES(and optionallyADMIN_PHONES) so that at least one admin can use the bot and assign roles via/set_role.
For Mini App URL and production deployment notes (reverse proxy, initData), see the README Setup and Docker sections.
Production: HTTPS
In production the application must be served over HTTPS (e.g. behind a reverse proxy such as nginx or Caddy with TLS). Without HTTPS, the Telegram Mini App initData and the calendar subscription token are sent in the clear; an attacker on the same network could capture them and gain access to the calendar or impersonate the user. Deploy the HTTP server behind a proxy that terminates TLS and forwards requests to the app.