TelegramBotAdmin/LOCAL_SETUP.md

Local setup

This fork adds a local Ant Design Pro admin panel, Telegram private management, Mongo-backed giveaways, per-chat points, and a cross-Bot teacher directory to WilliamButcherBot.

Requirements

• Python 3.12 and uv
• Node.js 20 or newer
• MongoDB 7, or Docker with Docker Compose
• One or more Telegram bot tokens, an API ID/API hash, and a test group

Bot credentials are managed in the web panel. Sensitive values are stored in runtime/bot_profiles.json with mode 0600 and are never returned by the API. Each enabled Bot runs in its own process and uses an isolated MongoDB database; the Web administrator account and sessions remain in the shared control database.

Configure

cp config.env.template config.env

The environment file now contains only process-level settings. Set at least:

• MONGO_URL
• Optional admin bind, session, and upload settings

After login, open System settings and configure the shared Telegram API ID and API Hash. Add any number of Bot profiles; every profile has its own Token, SUDOERS, log groups, media relay group, Pyrogram session, and worker process. Enabled profiles start automatically as soon as the shared API credentials are complete. Token testing uses Telegram's official getMe endpoint.

The admin panel defaults are:

• Address: http://127.0.0.1:8088/admin
• Username: admin
• Initial password: qwe0.123456

The initial password is only used to create the first admin record. The first login must change it. Later changes to the environment value do not overwrite an existing password hash.

Run with Docker Compose

docker compose up --build

The container listens on 0.0.0.0:8088, while Compose publishes it only at 127.0.0.1:8088. MongoDB is not exposed to the host. Bot profiles persist in the bind-mounted runtime/ directory.

Run from the workspace

uv sync --python 3.12
cd admin-web
npm ci
npm run build
cd ..
uv run python launcher.py

For frontend development, keep the bot/API on port 8088 and run:

cd admin-web
npm run dev

Umi runs on port 8090 and proxies /api/admin/* to the Python service. The launcher keeps the control panel on port 8088 and starts one internal worker per enabled Bot. The Bot selector in the header routes group operations to the selected worker.

Telegram commands

User points commands:

/points
/checkin
/points_rank
/points_history

Administrator points commands:

/points_add <user> <amount> <reason>
/points_deduct <user> <amount> <reason>
/points_set <user> <balance> <reason>
/points_toggle <enable|disable>

Giveaway commands:

/giveaway 1h | First:1:50, Second:3:10 | Launch | Description | 20 | 5 | 2
/gjoin <id>
/glist
/gparticipants <id>
/gend <id>
/gcancel <id>
/greroll <id> [tier]
/gremove <id> <user_id> [no-refund]
/gban <user> [reason]
/gunban <user>

Private administration:

/manage [chat_id]
/cancel

Private menu flows expire after ten minutes. Every action rechecks the operator's current Telegram permissions; SUDOERS can manage all known groups.

Teacher directory:

/directory
/nearby
/teacher_rank
/teacher_apply
/teacher_list
/teacher_unlist
/teacher_online
/teacher_offline

Assign the Teacher directory manager role to every Bot that should expose these commands. Teacher identity, location, listing, and presence are global across all configured Bots. A user must first run /directory in a managed group so the supervisor can perform a live membership check.

Open Teacher directory in the Web panel to review applications and configure OpenStreetMap Nominatim. Public Nominatim reverse geocoding remains disabled until a contact email or URL is configured. It is globally limited to one request per second, cached, and only receives coordinates after the user accepts the Telegram privacy prompt. Distance search continues to work when Nominatim is disabled or unavailable.

Verification

uv run ruff check wbb tests sample_config.py
uv run python -m compileall -q wbb
uv run pytest
cd admin-web
npm ci
npm run typecheck
npm test
npm run build
cd ..
docker compose config

Ruff is scoped in pyproject.toml to this fork's new and modified feature modules; the untouched upstream bot still has its pre-existing lint backlog.

Real Telegram group acceptance still requires API ID/API Hash and a disposable test group. Do not use a production group for the first run.