- Nov 9, 2026
- 3 min read
Homelab Deploy: Docker Gotchas and Lessons From a Telegram Bot
The code worked on my PC on day one. Running it 24/7 on the homelab taught me a few more things.
The deployment
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends tzdata && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY community_bot.py /app/community_bot.py
RUN mkdir /app/data && chown -R 1000:1000 /app
USER 1000:1000
CMD ["python3", "community_bot.py"]
services:
bot:
build: .
env_file: .env # secrets read at runtime, never baked into the image
volumes:
- ./data:/app/data # SQLite survives container rebuilds
restart: unless-stopped
init: true
One file, no pip install. tzdata is there because the digest runs on Europe/Zurich time. A Makefile wraps
run / up / down / logs / test / unban, and make help lists them.
Gotcha 1: Docker creates ./data as root
If the bind-mounted folder doesn’t exist, Docker creates it owned by root, and the container (UID 1000) fails
with unable to open database file. The fix:
sudo docker compose down
sudo mkdir -p data && sudo chown -R 1000:1000 data
sudo docker compose up --build -d
Local mode and Compose use the same ./data/community.sqlite3, so I can stop one and start the other without
losing state. Never both: they would fight over the token and the database.
Gotcha 2: the group changed its ID
Telegram upgraded my basic group to a supergroup, and the chat ID changed.
The confusing part: the old ID still returned the group title from getChat. Only getChatMember revealed
parameters.migrate_to_chat_id. The bot now alerts if join requests or messages arrive from a group that isn’t
the configured one (“check whether Telegram migrated the group”).
Gotcha 3: preflight before polling
At startup the bot checks it’s an admin with can_invite_users, can_delete_messages and
can_restrict_members, and refuses to start without them. A bot that silently fails to delete spam is worse than
one that won’t start.
Also: you have to /start the bot in a private chat before it can message you, and only invite links that
require admin approval create join requests.
Live checks in a checklist
Offline tests cover behavior and failures. Real Telegram behavior I checked by hand, tracked in tbc.md:
- Owner scoring, automatic deletion, Delete from review, owner ban exemption
- Edited message scored again and deleted
-
/digest preview - Join approval from a spare account
- Keep from review
- Second-strike ban of a normal member
- First real nightly digest
The owner is exempt from bans, so testing the ban needs a spare account. Easy to forget until you try.
Lessons
- A PIO with numbered behavior rules is enough to build from. Each rule became a test.
- Write down before acting (ledger + keyed actions + outbox) makes a bot safe to restart, and costs little.
- Classifier + thresholds + human review beats asking an LLM “should I delete this?”.
- Standard library only was the right call for a 550-line service. Nothing to update, nothing to audit.
- Write ADRs during the build, not after. I wrote ADR-001 a week later by reading my own code. It was doable, but I had to work out decisions I’d once made on purpose.
- Fill in or delete template files. A stale
status.jsonmisleads every agent that reads it.
What’s next
- Measure: false deletions, review load, and spam caught per week, then narrow the 0.35–0.90 review band.
- Images: spam bots increasingly post a picture with no text.
- Proper project metadata (
status.json,roadmap.yaml,decisions.ndjson) so the portfolio orchestrator can track this bot like the others.
Part 6 of 6. Start with the series overview.