Arnike/duty-teller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 14 Wiki Activity
Files
7ba4771501ce0d91545d0dc99a8cef9f66f7c1a5
duty-teller/docs/configuration.md
Nikolay Tatarinov 7ba4771501
All checks were successful
CI / lint-and-test (push) Successful in 24s
Details
docs: update environment configuration and API documentation 
- Revised the `.env.example` file to clarify the purpose of the `MINI_APP_SKIP_AUTH` variable, emphasizing its insecure nature and restriction to development use only.
- Updated the `README.md` to reflect changes in API authentication requirements, specifying that unauthenticated access to `/api/duties` and `/api/calendar-events` is only allowed with `MINI_APP_SKIP_AUTH=1`.
- Enhanced `configuration.md` to detail the implications of using `MINI_APP_SKIP_AUTH` for API access without Telegram initData.
- Removed the `_is_private_client` function and its associated tests, streamlining the codebase and focusing on the current authentication model.
- Added logging in `run.py` to warn when `MINI_APP_SKIP_AUTH` is enabled, highlighting the security risks.
2026-02-21 15:13:39 +03:00

4.2 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.
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.