diff --git a/README.md b/README.md
index e618c87..a7c3951 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,70 @@
-# TelegramBotTemplate
+<h3 align="center">TelegramBotTemplate</h3>
+
+<div align="center">
+
+[![Status](./docs/status-active-success.svg)]()
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE)
+
+</div>
+
+
+## 📝 Содержание
+
+- [О проекте](#about)
+- [Установка и запуск](#install)
+
+
+## 🧐 О проекте <a name = "about"></a>
+
+Проект шаблон с небольшими примерами реализации states, factory, и callbacks. Упор был сделан на отказоустойчивость и более простую поддержку проекта при его росте
+
+## 🎈 Установка и запуск <a name = "install"></a>
+
+Для установки необходимо выполнить установку компонентов в системе Ubuntu:
+
+```
+sudo apt update
+sudo apt install -y git docker.io docker-compose
+```
+
+Далее:
+- Получить API_TOKEN в [ссылка](https://t.me/botFather)
+
+### В папке с проектом:
+для систем Ubuntu:
+```
+python -m venv venv
+source ./venv/bin/activate
+./venv/bin/python -m pip install -r requirements.txt
+```
+для систем Windows:
+```
+python -m venv venv
+./venv/Scripts/activate
+./venv/Scripts/python -m pip install -r requirements.txt
+```
+создайте в папке проекта .env файл, и поместите значения следующим образом:
+```
+# Show debug messages in sys.out
+DEBUG=True
+
+# Telegram
+API_TOKEN=Ваш_токен
+
+# Database Postgres
+DATABASE_URL_LOCAL_MIGRATE=postgresql+asyncpg://admin:admin@localhost:5432/postgresdb
+POSTGRES_USER=admin
+POSTGRES_PASSWORD=admin
+POSTGRES_PORT=5432
+POSTGRES_DB=postgresdb
+PGDATA=/var/lib/postgresql/data/pgdata
+```
+
+Останется собрать всё это для работы:
+### Команда:
+
+> sudo docker compose --file 'docker-compose.dev.yaml' up -d
+
+После запуска проекта, запустите миграцию моделей в базу данных
+> alembic upgrade head