Arnike/duty-teller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
f8aceabab5e3ea4d61ff7795d248f898c0afaddf
duty-teller/docs/configuration.md
Nikolay Tatarinov d5da265b5f
All checks were successful
CI / lint-and-test (push) Successful in 24s
Details
feat: enhance HTTP handling and configuration 
- Introduced a new utility function `safe_urlopen` to ensure only allowed URL schemes (http, https) are opened, enhancing security against path traversal vulnerabilities.
- Updated the `run.py` and `calendar_ics.py` files to utilize `safe_urlopen` for HTTP requests, improving error handling and security.
- Added `HTTP_HOST` configuration to the settings, allowing dynamic binding of the HTTP server host.
- Revised the `.env.example` file to include the new `HTTP_HOST` variable with a description.
- Enhanced tests for `safe_urlopen` to validate behavior with disallowed URL schemes and ensure proper integration in existing functionality.
2026-02-24 14:16:34 +03:00

4.9 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_HOST string 127.0.0.1 Host to bind the HTTP server to. Use 127.0.0.1 to listen only on localhost; use 0.0.0.0 to accept connections from all interfaces (e.g. when behind a reverse proxy on another machine).
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 sends a new message, unpins the old one and pins the new one. If enabled, pinning the new message sends a Telegram notification (“Bot pinned a message”). Set to 0, false, or no to pin without 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.