savagedb_bot/README_DOCKER.md

# SalvageDB Telegram Bot - Docker Deployment

Полная инструкция по развертыванию SalvageDB Telegram Bot в Docker контейнере.

## 📋 Требования

- Docker Engine 20.10+
- Docker Compose 2.0+
- Минимум 512 MB RAM
- Доступ к Oracle Database

## 🚀 Быстрый старт

### 1. Настройка конфигурации

Отредактируйте файл `docker-compose.yml` и замените значения по умолчанию на ваши:

```yaml
environment:
  # Telegram Bot настройки
  - BOT_TOKEN=your_actual_bot_token_here  # Замените на токен от @BotFather
  - BOT_NAME=SalvageDB Bot
  - ADMIN_USER_ID=your_telegram_user_id   # Замените на ваш Telegram ID
  
  # База данных Oracle
  - db_user=your_actual_db_user           # Замените на пользователя БД
  - db_password=your_actual_db_password   # Замените на пароль БД
  - db_dsn=your_db_host:1521/service_name # Замените на DSN вашей БД
```

**Обязательно замените:**
- `BOT_TOKEN` - токен от @BotFather
- `ADMIN_USER_ID` - ваш Telegram ID для админ-функций
- `db_user`, `db_password`, `db_dsn` - настройки Oracle DB

### 2. Создание необходимых директорий

```bash
# Создаем директории для данных
mkdir -p logs images data

# Устанавливаем права доступа (Linux/macOS)
chmod 755 logs images data
```

### 3. Запуск контейнера

```bash
# Сборка и запуск
docker-compose up --build -d

# Проверка статуса
docker-compose ps

# Просмотр логов
docker-compose logs -f salvagedb-bot
```

## 📁 Структура проекта

```
salvagedb_bot/
├── Dockerfile              # Конфигурация Docker образа
├── docker-compose.yml      # Orchestration конфигурация (содержит все настройки)
├── docker-entrypoint.sh    # Скрипт инициализации
├── .dockerignore           # Исключения для Docker
├── env.example             # Пример переменных (справочно)
├── requirements.txt        # Python зависимости
├── main.py                 # Основной код бота
├── db.py                   # Модуль работы с БД
├── middlewares/            # Middleware компоненты
├── logs/                   # Логи приложения (volume)
├── images/                 # Изображения автомобилей (volume)
└── data/                   # Дополнительные данные (volume)
```

## 🔧 Конфигурация

### Переменные окружения в docker-compose.yml

Все настройки находятся в файле `docker-compose.yml` в секции `environment`:

| Переменная | Описание | Значение по умолчанию |
|-----------|----------|----------------------|
| `BOT_TOKEN` | Токен Telegram бота | `your_bot_token_here` ⚠️ |
| `BOT_NAME` | Имя бота | `SalvageDB Bot` |
| `ADMIN_USER_ID` | ID администратора | `123456789` ⚠️ |
| `DECODE_PRICE` | Цена декодирования VIN | `1` |
| `CHECK_PRICE` | Цена проверки повреждений | `10` |
| `IMG_PRICE` | Цена доступа к фото | `100` |
| `db_user` | Пользователь Oracle DB | `your_db_user` ⚠️ |
| `db_password` | Пароль Oracle DB | `your_db_password` ⚠️ |
| `db_dsn` | DSN строка Oracle DB | `localhost:1521/XEPDB1` ⚠️ |
| `DEBUG` | Режим отладки | `0` |
| `TZ` | Часовой пояс | `UTC` |

**⚠️ Обязательно замените** отмеченные значения на реальные!

### Volumes

- `./logs:/home/salvagebot/app/logs` - Логи приложения
- `./images:/home/salvagebot/app/images:ro` - Изображения (read-only)
- `./data:/home/salvagebot/app/data` - Дополнительные данные

## 🛠️ Управление контейнером

### Основные команды

```bash
# Запуск
docker-compose up -d

# Остановка
docker-compose down

# Перезапуск
docker-compose restart

# Пересборка и запуск
docker-compose up --build -d

# Просмотр логов в реальном времени
docker-compose logs -f salvagedb-bot

# Подключение к контейнеру
docker-compose exec salvagedb-bot bash

# Просмотр статуса
docker-compose ps
```

### Мониторинг

```bash
# Проверка здоровья контейнера
docker-compose exec salvagedb-bot python -c "print('Bot is healthy!')"

# Статистика ресурсов
docker stats salvagedb-telegram-bot

# Информация о контейнере
docker inspect salvagedb-telegram-bot
```

## 📊 Логирование

### Структура логов

Логи сохраняются в директории `./logs/`:
- `salvagedb_bot.log` - текущий лог файл
- `salvagedb_bot.log.YYYY-MM-DD` - архивные логи

### Конфигурация логирования

- **Ротация:** ежедневно в полночь
- **Хранение:** 30 дней
- **Формат:** `YYYY-MM-DD HH:MM:SS - module - LEVEL - message`
- **Уровни:** INFO, WARNING, ERROR

## 🔒 Безопасность

### Рекомендации

1. **Переменные окружения:**
   - Замените все placeholder значения в docker-compose.yml
   - Используйте сильные пароли для БД
   - Ограничьте доступ к токену бота

2. **Сетевая безопасность:**
   - Контейнер работает в изолированной сети
   - Нет открытых портов (только исходящие соединения)

3. **Файловая система:**
   - Приложение работает под непривилегированным пользователем
   - Read-only монтирование для изображений

## 🐛 Устранение неполадок

### Проблемы с Oracle

```bash
# Проверка Oracle client в контейнере
docker-compose exec salvagedb-bot python -c "import oracledb; print(oracledb.version)"

# Тест подключения к БД
docker-compose exec salvagedb-bot python -c "
import oracledb
import os
conn = oracledb.connect(user=os.getenv('db_user'), password=os.getenv('db_password'), dsn=os.getenv('db_dsn'))
print('Connection successful!')
conn.close()
"
```

### Проблемы с ботом

```bash
# Проверка токена бота
docker-compose exec salvagedb-bot python -c "
import os
print('Bot token length:', len(os.getenv('BOT_TOKEN', '')))
"

# Проверка aiogram
docker-compose exec salvagedb-bot python -c "import aiogram; print('aiogram version:', aiogram.__version__)"
```

### Логи отладки

```bash
# Включить DEBUG режим (отредактировать docker-compose.yml)
# Изменить: DEBUG=1
docker-compose restart

# Просмотр подробных логов
docker-compose logs -f --tail=100 salvagedb-bot
```

## 🔄 Обновление

```bash
# Остановить контейнер
docker-compose down

# Обновить код
git pull

# Пересобрать и запустить
docker-compose up --build -d

# Проверить статус
docker-compose logs -f salvagedb-bot
```

## 📞 Поддержка

При возникновении проблем:

1. Проверьте логи: `docker-compose logs salvagedb-bot`
2. Убедитесь в правильности переменных в docker-compose.yml
3. Проверьте подключение к Oracle DB
4. Проверьте валидность токена бота

## 🏷️ Теги версий

- `latest` - последняя стабильная версия
- `dev` - версия для разработки
- `v1.x.x` - конкретные релизы