From 0d3e45c728ca791d87faa9ff62fecac46cd88f0b Mon Sep 17 00:00:00 2001
From: Ruslan Starkov <GraffixBoy420@yandex.ru>
Date: Mon, 5 Jan 2026 19:10:03 +0300
Subject: [PATCH] containerization

---
 .dockerignore      |  68 +++++++++
 .env.example       |   3 +
 .gitignore         |  55 +++++++
 DOCKER.md          | 359 ++++++++++++++++++++++++++++++++++++++++++++
 Dockerfile         |  31 ++++
 QUICKSTART.md      |  91 +++++++++++
 README.md          |  18 +++
 docker-compose.yml |  38 +++++
 src/README.md      | 365 +++++++++++++++++++++++++++++++++++++++++++++
 src/code/config.py |   4 +-
 10 files changed, 1031 insertions(+), 1 deletion(-)
 create mode 100644 .dockerignore
 create mode 100644 .env.example
 create mode 100644 .gitignore
 create mode 100644 DOCKER.md
 create mode 100644 Dockerfile
 create mode 100644 QUICKSTART.md
 create mode 100644 docker-compose.yml
 create mode 100644 src/README.md

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..550f414
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,68 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+logs/
+*.log
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# Documentation
+docs/
+reports/
+site/
+task/
+*.md
+!requirements.txt
+
+# Cache (будет монтироваться через volume)
+src/data/cache/
+src/data/users/
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
+.cache/
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..d0d403b
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,3 @@
+# Telegram Bot Configuration
+# Получите токен у @BotFather в Telegram
+BOT_TOKEN=your_bot_token_here
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..084abc8
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,55 @@
+# Переменные окружения
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Logs
+logs/
+*.log
+
+# Данные пользователей и кеш
+src/data/cache/
+src/data/users/
+
+# Temporary files
+*.tmp
+*.bak
+.cache/
+
+# OS
+Thumbs.db
diff --git a/DOCKER.md b/DOCKER.md
new file mode 100644
index 0000000..e7a18e7
--- /dev/null
+++ b/DOCKER.md
@@ -0,0 +1,359 @@
+# 🐳 Docker - Руководство по развертыванию
+
+## Содержание
+- [Быстрый старт](#быстрый-старт)
+- [Подробная настройка](#подробная-настройка)
+- [Управление контейнером](#управление-контейнером)
+- [Мониторинг и отладка](#мониторинг-и-отладка)
+- [Производственное развертывание](#производственное-развертывание)
+
+## Быстрый старт
+
+### 1. Установка Docker
+
+**Ubuntu/Debian:**
+```bash
+# Установка Docker
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+
+# Установка Docker Compose
+sudo apt install docker-compose-plugin
+
+# Добавление пользователя в группу docker
+sudo usermod -aG docker $USER
+newgrp docker
+```
+
+**macOS:**
+```bash
+# Установка через Homebrew
+brew install --cask docker
+```
+
+**Windows:**
+Скачайте [Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)
+
+### 2. Настройка проекта
+
+```bash
+# Клонирование репозитория
+git clone https://github.com/EDeev/mospoly-helper.git
+cd mospoly-helper
+
+# Создание файла .env
+cp .env.example .env
+
+# Редактирование .env (добавьте ваш BOT_TOKEN)
+nano .env
+```
+
+### 3. Запуск
+
+```bash
+# Сборка и запуск в фоновом режиме
+docker-compose up -d
+
+# Проверка статуса
+docker-compose ps
+
+# Просмотр логов
+docker-compose logs -f
+```
+
+## Подробная настройка
+
+### Структура Docker-файлов
+
+```
+mospoly-helper/
+├── Dockerfile              # Описание образа контейнера
+├── docker-compose.yml      # Конфигурация сервисов
+├── .dockerignore          # Исключения при сборке
+├── .env                   # Переменные окружения (не в Git!)
+└── .env.example           # Шаблон переменных окружения
+```
+
+### Переменные окружения (.env)
+
+```env
+# Основная конфигурация
+BOT_TOKEN=your_bot_token_here
+```
+
+### Volumes (монтируемые директории)
+
+Данные сохраняются между перезапусками контейнера благодаря volumes:
+
+| Локальная директория | Директория в контейнере | Назначение |
+|----------------------|-------------------------|------------|
+| `./src/videos` | `/app/src/videos` | Исходные видеофрагменты (read-only) |
+| `./src/data/cache` | `/app/src/data/cache` | Кеш сгенерированных маршрутов |
+| `./src/data/users` | `/app/src/data/users` | Данные пользователей |
+| `./logs` | `/app/logs` | Журналы работы бота |
+
+## Управление контейнером
+
+### Основные команды
+
+```bash
+# Запуск
+docker-compose up -d                    # В фоновом режиме
+docker-compose up                       # С выводом логов в терминал
+
+# Остановка
+docker-compose stop                     # Остановка без удаления
+docker-compose down                     # Остановка и удаление контейнера
+
+# Перезапуск
+docker-compose restart                  # Быстрый перезапуск
+docker-compose down && docker-compose up -d  # Полный перезапуск
+
+# Пересборка
+docker-compose build                    # Пересборка образа
+docker-compose up -d --build            # Пересборка и запуск
+```
+
+### Работа с контейнером
+
+```bash
+# Выполнение команд внутри контейнера
+docker-compose exec mospoly-helper-bot python combine.py
+
+# Интерактивная оболочка
+docker-compose exec mospoly-helper-bot /bin/bash
+
+# Копирование файлов
+docker cp local_file.txt mospoly-helper-bot:/app/
+docker cp mospoly-helper-bot:/app/file.txt ./
+```
+
+## Мониторинг и отладка
+
+### Просмотр логов
+
+```bash
+# Все логи
+docker-compose logs
+
+# Последние 100 строк с обновлением
+docker-compose logs --tail=100 -f
+
+# Логи за последний час
+docker-compose logs --since 1h
+
+# Логи конкретного сервиса
+docker-compose logs mospoly-helper-bot
+```
+
+### Проверка состояния
+
+```bash
+# Статус контейнеров
+docker-compose ps
+
+# Использование ресурсов
+docker stats mospoly-helper-bot
+
+# Проверка health check
+docker inspect --format='{{.State.Health.Status}}' mospoly-helper-bot
+```
+
+### Отладка проблем
+
+```bash
+# Проверка сети
+docker network inspect mospoly-helper_default
+
+# Инспектирование контейнера
+docker inspect mospoly-helper-bot
+
+# События Docker
+docker events --filter container=mospoly-helper-bot
+```
+
+## Производственное развертывание
+
+### 1. Подготовка сервера
+
+```bash
+# Обновление системы
+sudo apt update && sudo apt upgrade -y
+
+# Установка Docker и Docker Compose
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+sudo apt install docker-compose-plugin
+
+# Создание пользователя для бота
+sudo useradd -m -s /bin/bash botuser
+sudo usermod -aG docker botuser
+```
+
+### 2. Настройка автозапуска
+
+Docker Compose автоматически настроит перезапуск контейнера благодаря `restart: unless-stopped` в docker-compose.yml.
+
+Проверка:
+```bash
+# Перезагрузка сервера
+sudo reboot
+
+# После перезагрузки проверка
+docker-compose ps
+```
+
+### 3. Настройка logrotate
+
+Создайте файл `/etc/logrotate.d/docker-containers`:
+
+```
+/var/lib/docker/containers/*/*.log {
+    rotate 7
+    daily
+    compress
+    missingok
+    delaycompress
+    copytruncate
+}
+```
+
+### 4. Мониторинг
+
+Используйте systemd для мониторинга:
+
+```bash
+# Создайте файл /etc/systemd/system/mospoly-bot.service
+[Unit]
+Description=MosPoly Helper Bot
+Requires=docker.service
+After=docker.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+WorkingDirectory=/path/to/mospoly-helper
+ExecStart=/usr/bin/docker-compose up -d
+ExecStop=/usr/bin/docker-compose down
+User=botuser
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+# Активация сервиса
+sudo systemctl daemon-reload
+sudo systemctl enable mospoly-bot.service
+sudo systemctl start mospoly-bot.service
+sudo systemctl status mospoly-bot.service
+```
+
+### 5. Резервное копирование
+
+```bash
+# Скрипт резервного копирования (backup.sh)
+#!/bin/bash
+DATE=$(date +%Y%m%d_%H%M%S)
+BACKUP_DIR="/backup/mospoly-bot"
+
+mkdir -p $BACKUP_DIR
+
+# Остановка контейнера
+docker-compose stop
+
+# Резервное копирование данных
+tar -czf $BACKUP_DIR/data_$DATE.tar.gz ./src/data
+
+# Запуск контейнера
+docker-compose start
+
+# Удаление старых резервных копий (старше 30 дней)
+find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete
+```
+
+Добавьте в crontab:
+```bash
+# Резервное копирование каждый день в 3:00
+0 3 * * * /path/to/backup.sh
+```
+
+## Обновление бота
+
+```bash
+# 1. Получение обновлений
+git pull
+
+# 2. Остановка контейнера
+docker-compose down
+
+# 3. Пересборка образа
+docker-compose build
+
+# 4. Запуск обновленной версии
+docker-compose up -d
+
+# 5. Проверка логов
+docker-compose logs -f
+```
+
+## Очистка ресурсов
+
+```bash
+# Удаление неиспользуемых образов
+docker image prune -a
+
+# Удаление неиспользуемых volumes
+docker volume prune
+
+# Полная очистка системы Docker
+docker system prune -a --volumes
+```
+
+## Решение типичных проблем
+
+### Проблема: Контейнер не запускается
+
+```bash
+# Проверка логов
+docker-compose logs
+
+# Проверка переменных окружения
+docker-compose config
+
+# Пересборка образа
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+### Проблема: Недостаточно места на диске
+
+```bash
+# Проверка использования места
+docker system df
+
+# Очистка
+docker system prune -a
+```
+
+### Проблема: Контейнер постоянно перезапускается
+
+```bash
+# Проверка статуса health check
+docker inspect --format='{{.State.Health}}' mospoly-helper-bot
+
+# Запуск без автоперезапуска для отладки
+docker-compose run --rm mospoly-helper-bot python bot.py
+```
+
+## Полезные ссылки
+
+- [Официальная документация Docker](https://docs.docker.com/)
+- [Docker Compose documentation](https://docs.docker.com/compose/)
+- [Best practices for writing Dockerfiles](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
+
+---
+
+<div align="center">
+<sub>Создано с ❤️ для удобства развертывания МосПолиХелпер</sub>
+</div>
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..2679cdc
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,31 @@
+# Используем официальный Python образ
+FROM python:3.10-slim
+
+# Устанавливаем рабочую директорию
+WORKDIR /app
+
+# Устанавливаем системные зависимости и FFmpeg
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+# Копируем requirements.txt
+COPY requirements.txt .
+
+# Устанавливаем Python зависимости
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Копируем исходный код проекта
+COPY src/ /app/src/
+
+# Создаем необходимые директории для данных
+RUN mkdir -p /app/src/data/cache \
+    /app/src/data/users \
+    /app/logs
+
+# Устанавливаем рабочую директорию для запуска бота
+WORKDIR /app/src/code
+
+# Команда для запуска бота
+CMD ["python", "bot.py"]
diff --git a/QUICKSTART.md b/QUICKSTART.md
new file mode 100644
index 0000000..6155319
--- /dev/null
+++ b/QUICKSTART.md
@@ -0,0 +1,91 @@
+# 🚀 Быстрый старт - МосПолиХелпер
+
+## Запуск за 3 минуты
+
+### Шаг 1: Клонирование репозитория
+```bash
+git clone https://github.com/EDeev/mospoly-helper.git
+cd mospoly-helper
+```
+
+### Шаг 2: Настройка токена бота
+```bash
+# Создайте файл .env из шаблона
+cp .env.example .env
+
+# Добавьте токен бота (получите у @BotFather в Telegram)
+echo "BOT_TOKEN=ваш_токен_здесь" > .env
+```
+
+### Шаг 3: Запуск через Docker
+```bash
+# Запуск бота
+docker-compose up -d
+
+# Проверка логов
+docker-compose logs -f
+```
+
+## Альтернатива: Запуск без Docker
+
+### Шаг 1: Установка зависимостей
+```bash
+# Установка Python зависимостей
+pip install -r requirements.txt
+
+# Установка FFmpeg
+# Ubuntu/Debian:
+sudo apt update && sudo apt install ffmpeg
+
+# macOS:
+brew install ffmpeg
+```
+
+### Шаг 2: Настройка токена
+```bash
+# Откройте src/code/config.py и замените токен
+nano src/code/config.py
+```
+
+### Шаг 3: Запуск
+```bash
+cd src/code
+python bot.py
+```
+
+## Проверка работы
+
+После запуска:
+1. Найдите бота в Telegram: [@MosPoly_Helperbot](https://t.me/MosPoly_Helperbot)
+2. Отправьте команду `/start`
+3. Попробуйте построить маршрут командой `/route`
+
+## Полезные команды Docker
+
+```bash
+# Остановка бота
+docker-compose down
+
+# Перезапуск
+docker-compose restart
+
+# Просмотр логов
+docker-compose logs -f
+
+# Обновление и перезапуск
+git pull
+docker-compose up -d --build
+```
+
+## Нужна помощь?
+
+- 📖 Подробная документация: [README.md](README.md)
+- 🐳 Руководство по Docker: [DOCKER.md](DOCKER.md)
+- 📧 Email: support@new-devs.ru
+- 🐙 Issues: [GitHub Issues](https://github.com/EDeev/mospoly-helper/issues)
+
+---
+
+<div align="center">
+<sub>Готово! Ваш бот запущен и готов к работе 🎉</sub>
+</div>
diff --git a/README.md b/README.md
index de9d0e2..f66ef40 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@
 [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
 [![Aiogram](https://img.shields.io/badge/Aiogram-3.0.0-green.svg)](https://aiogram.dev/)
 [![MoviePy](https://img.shields.io/badge/MoviePy-1.0.3-red.svg)](https://moviepy.readthedocs.io/)
+[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg?logo=docker&logoColor=white)](https://www.docker.com/)
 [![Bot](https://img.shields.io/badge/Telegram-@MosPoly__Helperbot-blue.svg)](https://t.me/MosPoly_Helperbot)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
@@ -38,6 +39,23 @@
 
 ## 🚀 Быстрый старт
 
+### 🐳 Запуск через Docker (рекомендуется)
+
+```bash
+# 1. Клонирование репозитория
+git clone https://github.com/EDeev/mospoly-helper.git
+cd mospoly-helper
+
+# 2. Настройка токена
+cp .env.example .env
+# Отредактируйте .env и добавьте ваш BOT_TOKEN
+
+# 3. Запуск
+docker-compose up -d
+```
+
+📖 **Подробнее**: [QUICKSTART.md](QUICKSTART.md) | [DOCKER.md](DOCKER.md)
+
 ### Команды бота
 
 - `/start` — Приветствие и инструкции
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..50d622b
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,38 @@
+version: '3.8'
+
+services:
+  mospoly-helper-bot:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: mospoly-helper-bot
+    restart: unless-stopped
+
+    environment:
+      # Токен бота из .env файла
+      - BOT_TOKEN=${BOT_TOKEN}
+
+    volumes:
+      # Монтируем папку с видео (исходники)
+      - ./src/videos:/app/src/videos:ro
+      # Монтируем папку с кешем (для сгенерированных видео)
+      - ./src/data/cache:/app/src/data/cache
+      # Монтируем папку с данными пользователей
+      - ./src/data/users:/app/src/data/users
+      # Монтируем папку с логами
+      - ./logs:/app/logs
+
+    # Настройки логирования Docker
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+    # Проверка здоровья контейнера
+    healthcheck:
+      test: ["CMD-SHELL", "pgrep -f 'python bot.py' || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000..8d0b91b
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,365 @@
+# МосПолиХелпер 🎓
+
+**Телеграм-бот для навигации по кампусам Московского Политехнического Университета**
+
+[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://python.org)
+[![Aiogram](https://img.shields.io/badge/Aiogram-3.0.0-green.svg)](https://aiogram.dev/)
+[![MoviePy](https://img.shields.io/badge/MoviePy-1.0.3-red.svg)](https://moviepy.readthedocs.io/)
+[![Bot](https://img.shields.io/badge/Telegram-@MosPoly__Helperbot-blue.svg)](https://t.me/MosPoly_Helperbot)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## 📋 Описание
+
+МосПолиХелпер — это практическое решение реальной проблемы ориентирования в кампусах Московского Политехнического Университета. Бот разработан студентами для студентов и предоставляет интерактивные видео-маршруты до любого кабинета в пяти основных кампусах университета.
+
+Проект создан в рамках проектной практики и демонстрирует применение современных технологий для решения повседневных задач студенческой жизни.
+
+### ✨ Основные возможности
+
+- 🗺️ **Интерактивная навигация** по 5 кампусам МосПолитеха
+- 🎥 **Динамические видео-маршруты** от входа на территорию или от входа в корпус
+- ⚡ **Мгновенная отдача** готовых маршрутов благодаря интеллектуальному кешированию
+- 📱 **Интуитивный интерфейс** с адаптивными inline-кнопками
+- 🔄 **Автоматическая обработка видео** с оптимизацией для Telegram (H.264, битрейт 1500k)
+- 🚀 **Высокая производительность** — время отклика менее 5 секунд для кешированных маршрутов
+- 📊 **Умная валидация** входных данных с подсказками пользователю
+
+### 🏢 Поддерживаемые кампусы
+
+| Кампус | Код | Формат номера кабинета | Пример |
+|--------|-----|------------------------|---------|
+| **Большая Семёновская** | `bs` | [корпус][этаж]-[номер] | `а1-01`, `б2-15` |
+| **Павла Корчагина** | `pk` | пк[корпус][этаж][номер] | `пк1201`, `пк2315` |
+| **Прянишникова** | `pr` | пр[корпус][этаж][номер] | `пр1101`, `пр2208` |
+| **Михалковская** | `mi` | м[корпус][этаж][номер] | `м1205`, `м3110` |
+| **Автозаводская** | `av` | ав[корпус][этаж][номер] | `ав2301`, `ав1105` |
+
+> 📝 **Важно**: Указывайте номер кабинета точно в том формате, как он указан в личном кабинете или расписании
+
+## 🚀 Быстрый старт
+
+### Команды бота
+
+- `/start` — Приветствие и инструкции
+- `/help` — Справка по командам
+- `/route` — Построить маршрут до кабинета
+
+### Использование
+
+1. Запустите бота командой `/start`
+2. Выберите команду `/route`
+3. Укажите кампус из предложенного списка
+4. Введите номер кабинета в точном формате
+5. Выберите тип маршрута (от территории или от входа в корпус)
+6. Получите видео с маршрутом
+
+## 🛠️ Архитектура и технический стек
+
+### 🧩 Технологии
+
+| Компонент | Технология | Версия | Назначение |
+|-----------|------------|---------|------------|
+| **Backend** | Python | 3.10+ | Основной язык разработки |
+| **Bot Framework** | Aiogram | 3.0.0 | Асинхронная работа с Telegram Bot API |
+| **Video Processing** | MoviePy | 1.0.3 | Обработка и монтаж видеофрагментов |
+| **Video Encoding** | FFmpeg | latest | Кодирование и оптимизация видео |
+| **Data Storage** | JSON | native | Хранение пользовательских сессий |
+| **State Management** | MemoryStorage | aiogram | Управление состояниями пользователей |
+
+### 🏗️ Модульная архитектура
+
+```
+src/code/
+├── bot.py            # 🚀 Точка входа и координация приложения
+├── config.py         # ⚙️  Конфигурационные параметры
+├── database.py       # 💾 Управление пользовательскими данными
+├── handlers.py       # 🎛️  Обработчики команд и callback'ов
+├── init.py           # 🔧 Инициализация компонентов бота
+├── scripts.py        # 🎬 Обработка видео и формирование маршрутов
+└── combine.py        # 🔄 Утилита для предварительной генерации кеша
+```
+
+**Принципы проектирования:**
+- **Single Responsibility** — каждый модуль отвечает за конкретную задачу
+- **Dependency Injection** — слабая связанность между компонентами
+- **Async/Await** — асинхронная обработка для высокой производительности
+- **Error Handling** — корректная обработка ошибок на всех уровнях
+
+## 📁 Структура данных и файловая система
+
+```
+📦 mospoly-helper/
+├── 📂 src/code/              # Исходный код
+├── 📂 data/                  # Рабочие данные
+│   ├── 📂 cache/             # Сгенерированные видеомаршруты
+│   │   ├── 📄 *-all.mp4      # Полные маршруты (от территории)
+│   │   └── 📄 *-small.mp4    # Короткие маршруты (от входа в корпус)
+│   ├── 📂 users/             # JSON-файлы сессий пользователей
+│   │   └── 📄 {user_id}.json # Данные конкретного пользователя
+│   └── 📂 videos/            # Библиотека исходных видеофрагментов
+│       ├── 📂 av/            # Автозаводская
+│       │   ├── 📂 buildings/ # Видео от входа до корпуса
+│       │   ├── 📂 floors/    # Видео по этажам
+│       │   └── 📂 offices/   # Видео до конкретных кабинетов
+│       ├── 📂 bs/            # Большая Семёновская
+│       ├── 📂 mi/            # Михалковская
+│       ├── 📂 pk/            # Павла Корчагина
+│       └── 📂 pr/            # Прянишникова
+├── 📂 logs/                  # Журналы работы (рекомендуется)
+├── 📄 Dockerfile             # Конфигурация Docker-образа
+├── 📄 docker-compose.yml     # Оркестрация контейнеров
+├── 📄 .env                   # Переменные окружения (создать из .env.example)
+└── 📄 .env.example           # Шаблон переменных окружения
+```
+
+## ⚡ Установка и настройка
+
+### 📋 Системные требования
+
+**Для запуска через Docker (рекомендуется):**
+- **OS**: Linux (Ubuntu 20.04+), macOS, Windows 10+
+- **Docker**: 20.10+ и Docker Compose
+- **RAM**: минимум 2 ГБ (рекомендуется 4 ГБ)
+- **Storage**: минимум 10 ГБ для видеофрагментов и кеша
+- **Network**: стабильное интернет-соединение
+
+**Для запуска без Docker:**
+- **OS**: Linux (Ubuntu 20.04+), macOS, Windows 10+
+- **Python**: 3.10 или выше
+- **FFmpeg**: последняя версия
+- **RAM**: минимум 2 ГБ (рекомендуется 4 ГБ)
+- **Storage**: минимум 10 ГБ для видеофрагментов и кеша
+- **Network**: стабильное интернет-соединение
+
+### 🔧 Установка зависимостей
+
+1. **Клонирование репозитория**
+```bash
+git clone https://github.com/EDeev/mospoly-helper.git
+cd mospoly-helper
+```
+
+2. **Установка Python-зависимостей**
+```bash
+pip install -r requirements.txt
+```
+
+3. **Установка FFmpeg**
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install ffmpeg
+```
+
+**macOS (с Homebrew):**
+```bash
+brew install ffmpeg
+```
+
+**Windows:**
+Скачайте с [официального сайта](https://ffmpeg.org/download.html) и добавьте в PATH
+
+### ⚙️ Конфигурация
+
+1. **Создание Telegram бота**
+   - Перейдите к [@BotFather](https://t.me/BotFather)
+   - Создайте нового бота командой `/newbot`
+   - Сохраните полученный токен
+
+2. **Настройка конфигурации**
+```python
+# config.py
+BOT_TOKEN = "YOUR_BOT_TOKEN_HERE"  # Замените на ваш токен
+```
+
+3. **Создание структуры каталогов**
+```bash
+mkdir -p data/{cache,users,videos/{av,bs,mi,pk,pr}/{buildings,floors,offices}}
+mkdir -p logs
+```
+
+### 🚀 Запуск
+
+#### 🐳 Запуск через Docker (рекомендуется)
+
+**1. Подготовка:**
+```bash
+# Создайте файл .env из примера
+cp .env.example .env
+
+# Отредактируйте .env и добавьте ваш токен бота
+nano .env  # или любой другой редактор
+```
+
+**2. Запуск контейнера:**
+```bash
+# Сборка и запуск в фоновом режиме
+docker-compose up -d
+
+# Просмотр логов
+docker-compose logs -f
+
+# Остановка контейнера
+docker-compose down
+
+# Перезапуск после изменений
+docker-compose restart
+```
+
+**3. Предварительная генерация кеша (опционально):**
+```bash
+docker-compose exec mospoly-helper-bot python combine.py
+```
+
+**Преимущества Docker:**
+- ✅ Изолированная среда выполнения
+- ✅ Автоматическая установка FFmpeg и всех зависимостей
+- ✅ Простое развертывание на сервере
+- ✅ Автоматический перезапуск при сбоях
+- ✅ Управление логами
+
+#### 💻 Запуск без Docker (альтернатива)
+
+**Основной режим:**
+```bash
+cd src/code
+python bot.py
+```
+
+**С логированием:**
+```bash
+python bot.py 2>&1 | tee ../../logs/bot.log
+```
+
+**Предварительная генерация кеша (опционально):**
+```bash
+python combine.py  # Генерирует кеш для всех доступных маршрутов
+```
+
+## 🎯 Алгоритмы и оптимизации
+
+### 🎬 Обработка видео
+
+Система обработки видео использует продвинутые техники оптимизации:
+
+```python
+# Параметры кодирования (scripts.py)
+full_clip.write_videofile(
+    filename,
+    fps=30,                    # Оптимальная частота кадров
+    codec="libx264",           # Эффективный кодек H.264
+    bitrate="1500k",           # Баланс качество/размер
+    preset="fast",             # Быстрое кодирование
+    ffmpeg_params=["-crf", "23"]  # Constant Rate Factor для качества
+)
+```
+
+**Применяемые оптимизации:**
+- ✂️ **Удаление аудиодорожки** — экономия 30-40% размера файла
+- ⏩ **Ускорение в 2 раза** — сокращение времени просмотра
+- 📐 **Изменение разрешения до 400px** — оптимизация для мобильных устройств
+- 🗜️ **CRF 23** — оптимальный баланс качества и размера файла
+
+### ⚡ Система кеширования
+
+**Двухуровневое кеширование:**
+1. **Полные маршруты** (`*-all.mp4`) — от входа на территорию
+2. **Короткие маршруты** (`*-small.mp4`) — от входа в корпус
+
+**Алгоритм проверки кеша:**
+```python
+# Проверка существования готового файла
+cache_path = f"../data/cache/{route_id}-{'all' if full_route else 'small'}.mp4"
+if os.path.exists(cache_path):
+    return cache_path  # Мгновенная отдача
+else:
+    return await make_full_clip(video_segments)  # Генерация нового
+```
+
+### 📊 Производительность
+
+| Метрика | Кешированный маршрут | Новый маршрут |
+|---------|---------------------|---------------|
+| **Время отклика** | < 3 секунды | 15-30 секунд |
+| **Размер файла** | 2-8 МБ | аналогично |
+| **Качество видео** | 400p, 30fps | аналогично |
+| **Нагрузка на CPU** | минимальная | высокая |
+
+## 🧪 Оптимизации производительности
+
+| Компонент | До оптимизации | После оптимизации | Улучшение |
+|-----------|----------------|-------------------|-----------|
+| **Размер видео** | 15-25 МБ | 2-8 МБ | 🔻 70% |
+| **Время генерации** | 45-60 сек | 15-30 сек | 🔻 50% |
+| **Время отдачи (кеш)** | N/A | < 3 сек | ⚡ мгновенно |
+| **Использование RAM** | 200-300 МБ | 100-150 МБ | 🔻 40% |
+
+## 📦 combine.py — Пакетная генерация кеша
+
+Утилита для предварительной генерации видеомаршрутов:
+
+```python
+async def combine_all_videos():
+    """
+    Массовая генерация кеша для всех доступных маршрутов
+    
+    Обрабатывает:
+    - Все корпуса: pr, pk, mi, av, bs
+    - Полные и короткие маршруты для каждого кабинета
+    - Пропускает несуществующие видеофрагменты
+    """
+    corpora = ["pr", "pk", "mi", "av", "bs"]
+    
+    for corpus in corpora:
+        offices_path = f"../videos/{corpus}/offices"
+        for video_file in os.listdir(offices_path):
+            # Генерация полного маршрута
+            await make_full_clip([building_path, floor_path, office_path])
+            # Генерация короткого маршрута  
+            await make_full_clip([floor_path, office_path])
+```
+
+**Использование:**
+```bash
+cd src/code
+python combine.py  # Запуск в фоновом режиме для больших объемов
+```
+
+## 👨‍💻 Команда разработки
+
+Проект создан в рамках проектной практики студентами группы **241-327** направления "Системная и программная инженерия":
+
+| Участник | Роль | Вклад | Контакты |
+|----------|------|-------|----------|
+| **[Деев Егор Викторович](https://github.com/EDeev)** | Tech Lead & Backend Developer | Архитектура системы, обработка видео, оптимизация производительности | [@EDeev](https://t.me/EDeev) |
+| **[Сапрыкин Пётр Иванович](https://github.com/PetrSaprykin)** | Frontend & UX Developer | Пользовательский интерфейс, логика взаимодействия, тестирование | [@PetrSaprykin](https://github.com/PetrSaprykin) |
+| **[Старков Руслан Владимирович](https://github.com/RayStar-k)** | DevOps & QA Engineer | Развертывание, мониторинг, обеспечение качества | [@RayStar-k](https://github.com/RayStar-k) |
+
+**Научное руководство:**
+- **Куратор практики**: Баринова Наталья Владимировна
+- **Кураторы проектной деятельности**: Киреева Галина Ивановна, Будылина Евгения Александровна
+
+## 📞 Поддержка и контакты
+
+### 🆘 Получение помощи
+
+**Официальные каналы поддержки:**
+
+1. **📧 Email**: [support@new-devs.ru](mailto:support@new-devs.ru)
+   - Время ответа: 24-48 часов
+   - Для технических вопросов и предложений
+
+2. **🐙 GitHub Issues**: [Создать issue](https://github.com/EDeev/mospoly-helper/issues)
+   - Для сообщений об ошибках и feature requests
+   - Публичное обсуждение и tracking
+
+## 📄 Лицензия и правовая информация
+
+Этот проект создан в учебных целях как работа по дисциплине "Проектной практики" в Московском Политехническом Университете, 2024-2025 учебный год.
+
+---
+
+<div align="center">
+<sub>МосПолиХелпер — делаем навигацию в университете простой и понятной! 🎓✨</sub>
+<p><sub>Создано с ❤️ студентами МосПолитеха для студенческого сообщества</sub></p>
+</div>
diff --git a/src/code/config.py b/src/code/config.py
index bd514c4..805d548 100644
--- a/src/code/config.py
+++ b/src/code/config.py
@@ -1 +1,3 @@
-BOT_TOKEN = "XXXXXXXXX"  # @MosPoly_Helperbot
\ No newline at end of file
+import os
+
+BOT_TOKEN = os.getenv("BOT_TOKEN", "XXXXXXXXX")  # @MosPoly_Helperbot
\ No newline at end of file