Arnike/duty-teller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
8091c608e880155af814c66344ffc8254b6dbda6
duty-teller/docs/configuration.md
Nikolay Tatarinov 8091c608e8
All checks were successful
CI / lint-and-test (push) Successful in 23s
Details
feat: add group duty pin notification feature 
- Introduced a new configuration option `DUTY_PIN_NOTIFY` to control whether the bot re-pins the duty message when updated, providing notifications to group members.
- Updated the architecture documentation to reflect the new functionality of re-pinning duty messages.
- Enhanced the `.env.example` file to include the new configuration option with a description.
- Added tests to verify the behavior of the new refresh pin command and its integration with the existing group duty pin functionality.
- Updated internationalization messages to include help text for the new `/refresh_pin` command.
2026-02-23 10:51:47 +03:00

4.6 KiB
Raw Blame History

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 and /api/calendar-events are allowed without Telegram initData. Dev only — never use in production.
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.
DUTY_PIN_NOTIFY 0, false, or no to disable 1 (enabled) When the pinned duty message is updated on schedule, the bot re-pins it so that group members get a Telegram notification (“Bot pinned a message”). Set to 0, false, or no to only edit the message without re-pinning (no notification). The first pin (e.g. when the bot is added to the group or on /pin_duty) is always silent.
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

  1. Copy .env.example to .env.
  2. Set BOT_TOKEN to the token from BotFather.
  3. Set ADMIN_USERNAMES (and optionally ADMIN_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.