Family Budget Bot

✔️ This bot is developed only for Telegram users

✔️ Database is shared for all users

✔️ Generating analytics for selected period

Disclaimer: this project is created for personal usage. Do a fork for playing with the code

🔨 Setup the project locally

💡 It includes 2 possible guides: for setting up it with docker 🐳 or without it.

🚧 Mandatory steps

Clone the project from GitHub

git clone [email protected]:parfeniukink/family_budget_bot.git

✖️ 🐳 Without docker

🔧 Setup the environment

For running the application locally without a tool like Docker you would need to install all dependencies by yourself.

First of all you have to install Python3.11 and SQLite3 on your machine since they are main infrastructure components.

More information about the installation process you can find HERE

Then you have to install Python dependencies that are used for running the application. For doing this we recommend using pipenv as a tool for managing your virtual environment and project dependencies (but if you prefer using conda for example feel free to do this).

# install the pipenv tool
pip install pipenv

# activate the virtual environment
pipenv shell

# install dependencies from the Pipfile.lock file
pipenv sync --dev

🗃️ Setup the database

For working with database the alembic too is used. To initiate a new database, run:

alembic upgrade head

More alembic commands

Generate a new migration file based on SQLAlchemy models

alembic revision --autogenerate -m "MESSAGE"

Upgrade database according to the last version of migrations

alembic upgrade head

Downgrade to the specific migration version

alembic downgrade 0e43c346b90d

P.S. This hash is taken from the generated file in the migrations folder

⚠️ Do not forget that alembic saves the migration version into the database. Then, when you do crusial database updates you might need to remove the revision ID from the database.

sqlite3 db.sqlite3
> delete from alembic_version;

🏃‍♂️ Run the application

For running the application locally you can use Uvicorn Python ASGI server. More information HERE

python -m src.run

The reload parameter will reload the Uvicorn server on any change in the project root

🐳 Using Docker

Since developers may use different operating system the Docker system is used in order to resolve the issue: "not working on my computer".

If more specifically, the Docker compose is used for better experience.

🛠️ Setting up the project

For setting up the project you just need to complete only a few steps:

• Install Docker [download page]
• Run Docker containers using docker-compose:

🏃‍♂️ Running docker containers

⚠️ This command should be ran in the project root folder (family_budget_bot/)*

docker-compose up -d

The -d means --detach that allows you to run the container in a background

More Docker commands:

# Shut down docker containers
docker-compose down

# Show logs
docker-compose logs

# Show logs in a real time
docker-compose logs -f

🔧 Configure the project

The project could be configurable by using the environment variables which are retrieved in src/settings.py file

The example of setting up the environment variable:

# on Unix
export TELEGRAM_BOT_API_KEY=1223713432:AASDEH5ocYq2jqeqpxqasn123e0B5YrUWubKo

# on Windows
$env:TELEGRAM_BOT_API_KEY = "1223713432:AASDEH5ocYq2jqeqpxqasn123e0B5YrUWubKo";

Using .env file

Or as a preffered alternative you may use the .env that is automatically complete the stuff above for you if you use pipenv tool.

It means you jsut need to complete next steps:

# create the .env file base on the .env.default file
cp .env.default .env

# activate the virtual environment & export all environment variables automatically ༼ つ ◕_◕ ༽つ━☆ﾟ.*･｡ﾟ
pipenv shell

🤔 Summary

• So now, the project is ready to be used as a Telegram bot backend.

Just go to the Telegram bot that you had created with BotFather and start working.