• 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

  1. A PIO with numbered behavior rules is enough to build from. Each rule became a test.
  2. Write down before acting (ledger + keyed actions + outbox) makes a bot safe to restart, and costs little.
  3. Classifier + thresholds + human review beats asking an LLM “should I delete this?”.
  4. Standard library only was the right call for a 550-line service. Nothing to update, nothing to audit.
  5. 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.
  6. Fill in or delete template files. A stale status.json misleads 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.