{"id":13567036,"url":"https://github.com/ohld/django-telegram-bot","last_synced_at":"2025-05-16T18:08:13.042Z","repository":{"id":38313585,"uuid":"308592630","full_name":"ohld/django-telegram-bot","owner":"ohld","description":"My sexy Django + python-telegram-bot + Celery + Redis + Postgres + Dokku + GitHub Actions template","archived":false,"fork":false,"pushed_at":"2024-04-17T18:10:55.000Z","size":232,"stargazers_count":714,"open_issues_count":11,"forks_count":171,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-03T17:13:40.038Z","etag":null,"topics":["celery","django","dokku","github-actions","postgresql","redis","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"https://t.me/ffmemesbot","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ohld.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-30T10:10:04.000Z","updated_at":"2025-04-01T11:48:07.000Z","dependencies_parsed_at":"2024-08-01T13:39:28.088Z","dependency_job_id":null,"html_url":"https://github.com/ohld/django-telegram-bot","commit_stats":null,"previous_names":[],"tags_count":6,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohld%2Fdjango-telegram-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohld%2Fdjango-telegram-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohld%2Fdjango-telegram-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ohld%2Fdjango-telegram-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ohld","download_url":"https://codeload.github.com/ohld/django-telegram-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248599787,"owners_count":21131362,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["celery","django","dokku","github-actions","postgresql","redis","telegram","telegram-bot"],"created_at":"2024-08-01T13:02:22.107Z","updated_at":"2025-04-12T16:43:45.711Z","avatar_url":"https://github.com/ohld.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# django-telegram-bot\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/50623190/201977740-68ef4044-9cfa-45da-8897-2a90ecfa33ae.png\" align=\"center\" height=\"350px\" weight=\"350px\"\u003e\n\u003c/p\u003e\n\nSexy Django + python-telegram-bot + Celery + Redis + Postgres + Dokku + GitHub Actions template. Production-ready Telegram bot with database, admin panel and a bunch of useful built-in methods.\n\n\n⭐ graph: \n[![Sparkline](https://stars.medv.io/ohld/django-telegram-bot.svg)](https://stars.medv.io/ohld/django-telegram-bot)\n\n\n### Check the example bot that uses the code from Main branch: [t.me/djangotelegrambot](https://t.me/djangotelegrambot)\n\n## Features\n\n* Database: Postgres, Sqlite3, MySQL - you decide!\n* Admin panel (thanks to [Django](https://docs.djangoproject.com/en/3.1/intro/tutorial01/))\n* Background jobs using [Celery](https://docs.celeryproject.org/en/stable/)\n* [Production-ready](https://github.com/ohld/django-telegram-bot/wiki/Production-Deployment-using-Dokku) deployment using [Dokku](https://dokku.com)\n* Telegram API usage in polling or [webhook mode](https://core.telegram.org/bots/api#setwebhook)\n* Export all users in `.csv`\n* Native telegram [commands in menu](https://github.com/ohld/django-telegram-bot/blob/main/.github/imgs/bot_commands_example.jpg)\n  * In order to edit or delete these commands you'll need to use `set_my_commands` bot's method just like in [tgbot.dispatcher.setup_my_commands](https://github.com/ohld/django-telegram-bot/blob/main/tgbot/dispatcher.py#L150-L156)\n\nBuilt-in Telegram bot methods:\n* `/broadcast` — send message to all users (admin command)\n* `/export_users` — bot sends you info about your users in .csv file (admin command)\n* `/stats` — show basic bot stats \n* `/ask_for_location` — log user location when received and reverse geocode it to get country, city, etc.\n\n\n## Content\n\n* [How to run locally](https://github.com/ohld/django-telegram-bot/#how-to-run)\n   * [Quickstart with polling and SQLite](https://github.com/ohld/django-telegram-bot/#quickstart-polling--sqlite)\n   * [Using docker-compose](https://github.com/ohld/django-telegram-bot/#run-locally-using-docker-compose)\n* [Deploy to production](https://github.com/ohld/django-telegram-bot/#deploy-to-production)\n   * [Using dokku](https://github.com/ohld/django-telegram-bot/#deploy-using-dokku-step-by-step)\n   * [Telegram webhook](https://github.com/ohld/django-telegram-bot/#https--telegram-bot-webhook)\n\n\n# How to run\n\n## Quickstart: Polling \u0026 SQLite\n\nThe fastest way to run the bot is to run it in polling mode using SQLite database without all Celery workers for background jobs. This should be enough for quickstart:\n\n``` bash\ngit clone https://github.com/ohld/django-telegram-bot\ncd django-telegram-bot\n```\n\nCreate virtual environment (optional)\n``` bash\npython3 -m venv dtb_venv\nsource dtb_venv/bin/activate\n```\n\nInstall all requirements:\n```\npip install -r requirements.txt\n```\n\nCreate `.env` file in root directory and copy-paste this or just run `cp .env_example .env`,\ndon't forget to change telegram token:\n``` bash \nDJANGO_DEBUG=True\nDATABASE_URL=sqlite:///db.sqlite3\nTELEGRAM_TOKEN=\u003cPASTE YOUR TELEGRAM TOKEN HERE\u003e\n```\n\nRun migrations to setup SQLite database:\n``` bash\npython manage.py migrate\n```\n\nCreate superuser to get access to admin panel:\n``` bash\npython manage.py createsuperuser\n```\n\nRun bot in polling mode:\n``` bash\npython run_polling.py \n```\n\nIf you want to open Django admin panel which will be located on http://localhost:8000/tgadmin/:\n``` bash\npython manage.py runserver\n```\n\n## Run locally using docker-compose\nIf you want just to run all the things locally, you can use Docker-compose which will start all containers for you.\n\n### Create .env file. \nYou can switch to PostgreSQL just by uncommenting it's `DATABASE_URL` and commenting SQLite variable.\n```bash\ncp .env_example .env\n```\n\n### Docker-compose\n\nTo run all services (Django, Postgres, Redis, Celery) at once:\n``` bash\ndocker-compose up -d --build\n```\n\nCheck status of the containers.\n``` bash\ndocker ps -a\n```\nIt should look similar to this:\n\u003cp align=\"left\"\u003e\n    \u003cimg src=\"https://github.com/ohld/django-telegram-bot/raw/main/.github/imgs/containers_status.png\"\u003e\n\u003c/p\u003e\n\nTry visit \u003ca href=\"http://0.0.0.0:8000/tgadmin\"\u003eDjango-admin panel\u003c/a\u003e.\n\n### Enter django shell:\n\n``` bash\ndocker exec -it dtb_django bash\n```\n\n### Create superuser for Django admin panel\n\n``` bash\npython manage.py createsuperuser\n```\n\n### To see logs of the container:\n\n``` bash\ndocker logs -f dtb_django\n```\n\n\n# Deploy to Production \n\nProduction stack will include these technologies:\n\n1) Postgres as main database for Django\n2) Celery + Redis + easy scalable workers \n3) Dokku as PaaS (will build app from sources and deploy it with zero downtime)\n\nAll app's services that are going to be launched in production can be found in `Procfile` file. It includes Django webserver (Telegram event processing + admin panel) and Celery workers (background and periodic jobs).\n\n## What is Dokku and how it works\n\n[Dokku](https://dokku.com/) is an open-source version of Heroku. \n\nI really like Heroku deployment approach: \n1) you push commit to Main branch of your Repo\n2) in couple minutes your new app is running\n3) if something breaks during deployment - old app will not be shut down\n\nYou can achieve the same approach with Dokku + Github Actions (just to trigger deployment).\n\nDokku uses [buildpacks](https://buildpacks.io/) technology to create a Docker image from the code. No Dockerfile needed. Speaking about Python, it requires `requirements.txt`, `Procfile` files to run the things up. Also files `DOKKU_SCALE` and `runtime.txt` are useful to tweak configs to make the deployed app even better. E.g. in `DOKKU_SCALE` you can specify how many app instances should be run behind built-in load balancer.\n\nOne disadvantage of Dokku that you should be warned about is that it can work with one server only. You can't just scale your app up to 2 machines using only small config change. You still can use several servers by providing correct .env URLs to deployed apps (e.g. DATABASE_URL) but it will require more time to setup.\n\n## Deploy using Dokku: step-by-step\n\nI assume that you already have [Dokku installed](https://dokku.com/docs/getting-started/installation/) on your server. Let's also assume that the address of your server is *\u003cYOURDOMAIN.COM\u003e* (you will need a domain to setup HTTPs for Telegram webhook support). I'd recommend to have at least [2GB RAM and 2 CPU cores](https://m.do.co/c/260555f64021).\n\n### Create Dokku app\n\n``` bash\ndokku apps:create dtb\n```\n\nYou might need to added `.env` variables to app, e.g. to specify Telegram token:\n\n``` bash\ndokku config:set dtb TELEGRAM_TOKEN=.....\n```\n\n### Postgres and Redis\n\n**Postgres** and **Redis** are configured as Dokku plugins on a server.\nThey will automatically add REDIS_URL \u0026 DATABASE_URL .env vars to the app after being linked.\nYou might need to install these Dokku plugins before.\n[Install Postgres](https://github.com/dokku/dokku-postgres),\n[install Redis](https://github.com/dokku/dokku-redis).\n\n``` bash\ndokku postgres:create dtb\ndokku postgres:link dtb dtb\n\ndokku redis:create dtb\ndokku redis:link dtb dtb\n```\n\n### Deploy on commit with Github Actions\n\nGo to file [.github/workflows/dokku.yml](https://github.com/ohld/django-telegram-bot/blob/main/.github/workflows/dokku.yml):\n\n1. Enter your host name (address of your server), \n2. Deployed dokku app name (in our case this is `dtb`),\n3. Set `SSH_PRIVATE_KEY` secret variable via GitHub repo settings. This private key should have the **root ssh access** to your server.\n\nThis will trigger Dokku's zero-downtime deployment. You would probably need to fork this repo to change file. \n\nAfter that you should see a green arrow ✅ at Github Actions tab that would mean your app is deployed successfully. If you see a red cross ❌ you can find the deployed logs in Github Actions tab and find out what went wrong.\n\n## HTTPS \u0026 Telegram bot webhook\n\n### Why you need to setup webhook\n\nBasic polling approach is really handy and can speed up development of Telegram bots. But it doesn't scale. Better approach is to allow Telegram servers push events (webhook messages) to your server when something happens with your Telegram bot. You can use built-in Dokku load-balancer to parallel event processing.\n\n### HTTPS using Letsencrypt plugin\n\nFor Telegram bot API webhook usage you'll need a **https** which can be setup using [Letsencrypt Dokku plugin](https://github.com/dokku/dokku-letsencrypt). You will need to attach a domain to your Django app before and specify a email (required by Letsencrypt) - you will receive notifications when certificates would become old. Make sure you achieved a successful deployment first (your app runs at \u003cYOURDOMAIN.COM\u003e, check in browser).\n\n``` bash\ndokku domains:add dtb \u003cYOURDOMAIN.COM\u003e\ndokku config:set --global DOKKU_LETSENCRYPT_EMAIL=\u003cYOUR@EMAIL.COM\u003e\ndokku letsencrypt:enable dtb\n```\n\n### Setup Telegram Bot API webhook URL\n\nYou need to tell Telegram servers where to send events of your Telegram bot. Just open in the browser:\n\n```\nhttps://api.telegram.org/bot\u003cTELEGRAM_TOKEN\u003e/setWebhook?url=https://\u003cYOURDOMAIN.COM\u003e/super_secter_webhook/\n```\n\n\n### After deployment\n\nYou can be sure that your app is deployed successfully if you see a green arrow at the latest workflow at Github Actions tab.\n\nYou would need to create a superuser to access an admin panel at https://\u003cYOURDOMAIN.COM\u003e/tgadmin. This can be done using a standard way using django shell:\n\n\n### Open shell in deployed app \n``` shell\ndokku enter dtb web \n```\n\n### Create Django super user\nBeing inside a container:\n``` bash\npython manage.py createsuperuser\n```\n\nAfter that you can open admin panel of your deployed app which is located at https://\u003cYOURDOMAIN.COM\u003e/tgadmin.\n\n### Read app logs\n\n``` bash\ndokku logs dtb -t\n```\n\n\n----\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohld%2Fdjango-telegram-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fohld%2Fdjango-telegram-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fohld%2Fdjango-telegram-bot/lists"}