telegram-powered digital garden

a very simple digital garden with telegram as a CMS.

two python utilities keep track of selected topics of a group with topics and populate a sqlite db with all past messages (fetch_all.py) and saves new messages as they're sent (main.py)

then a digital garden website gets dynamically generated, using fastapi + htmx, templating via jinja2, with infinite scrolling on the topics downloaded and recorded.

How to run (source, via python)

after creating a python environment (i usually use uv)

1. Create a .env (or otherwise set env vars):
   • TELEGRAM_API_ID=... (found on my.telegram.org)
   • TELEGRAM_API_HASH=... (found on my.telegram.org)
   • TELEGRAM_GROUP_ID=... (numeric ID of your group)
   • MEDIA_DIR=... (where to store downloaded media)
   • ADMIN_DISPLAY_NAME=... (what you wanna be called inside the website)
   • TOPIC_MAP_INTERNAL={"topic_name_1": topic_id_1, "topic_name_2": topic_id_2} (json with topic_id being the id of the first message of the topic)
   • TOPIC_MAP_EXTERNAL={"topic_name_1": topic_id_1, "topic_name_2": topic_id_2} (all internal topics will automatically be credited to the admin display name)
   • DB_DIR=/your/db/directory
   • MEDIA_DIR=/your/media/directory
   • SESSION_DIR=/your/session/directory

n.b. !! the db is always called garden.db, as the session is always called garden_client.session. bot of these files are automatically generated

2. Install deps inside pyproject.toml. you can do it via uv sync
3. Initial backfill (historical fetch of allowed topics):
   • python -m garden.bot.fetch_all
   • telegram will now ask you the credentials:
     • your phone number
     • the login code
     • your 2fa password

after that the garden_client.session will be created, and can be kept persistant so the bot can have access to the group.

4. Run the live bot to keep saving new messages:
   • python -m garden.bot.main

As you send or modify or delete messages in the group you can see the telegram process handle that.

Small note on why this is not a telegram bot

i wanted to do this via a bot but it kinda looks like,, it's not what bots are meant for, so you have to use your personal user session to use this utility, since half of the api i needed to read from the group requires user clients and not bots. i think it's an ok tradeoff for a personal project, this might not be suitable for a group though.

Mini web (FastAPI + HTMX)

• Start the web server:
  • uvicorn garden.web.server:app --reload
  • Open http://127.0.0.1:8000

How to deploy via docker-compose

1. set your env variables as shown before
2. put your garden_client.session file inside of the session folder you put in the .env, otherwise the bot will crash
3. make sure thew folder you put in the env have owner 1000:1000
4. run docker compose up -d

..and that's it! you can open it to http://127.0.0.1:8000

after checking everything works and you can open it locally, since the db and media folder are still empty we can run the backfill script via the container itself.

1. stop the bot via docker stop garden-bot
2. docker compose run --rm bot python -m garden.bot.fetch_all
3. wait for the download of everything
4. restart the bot via docker start garden-bot

and that's it! you can now use it/expose it as you may see fit.

things todo

server side

• add website preview
• handle pinned messages
• add migrations or move to Postgres.
• handle reaction to messages as tags

frontend

• separate my own things from the reposting

• truncate long text posts

• fix mobile view!!!!!

  • fix the 3 columns problem
  • fix the top nav (even if mobile still maybe would be nice to change)
  • make ui bigger on mobile
  • remove horizontal scrolling

• fix how colunms are balanced

• fix carousel heights for later notes' chunk (sigh)

• (custom for links) Extract links from hackerpost bot

• fix a bit the link view, maybe add title + description extraction

• create custom page for written things

deploy

• add ci integration

conclusions

this was fun! and now i get to never leave telegram to post and scroll endlessly until the end of time. hoo-ray. you can check the first instance of this here:

https://hauntmehaunt.me