BUH_bot/docs/DOCKER_GUIDE.md

# Docker Development & Deployment Guide

## 📦 Структура Docker-окружения

```
BUH_bot/
├── Dockerfile                 # Образ контейнера
├── docker-compose.yml         # Оркестрация
├── .dockerignore             # Исключения при сборке
├── start.sh / start.bat      # Скрипт запуска (Linux/Windows)
├── stop.sh / stop.bat        # Скрипт остановки (Linux/Windows)
├── .env                      # Переменные окружения
└── .env.example              # Пример конфигурации
```

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

### 1. Подготовка

**Linux/Mac:**
```bash
# Клонируем репозиторий
git clone <repo_url>
cd BUH_bot

# Создаём .env из примера
cp .env.example .env

# Редактируем .env и указываем TELEGRAM_BOT_TOKEN
nano .env
```

**Windows:**
```cmd
git clone <repo_url>
cd BUH_bot

copy .env.example .env
notepad .env
```

### 2. Запуск

**Linux/Mac:**
```bash
chmod +x start.sh stop.sh
./start.sh
```

**Windows:**
```cmd
start.bat
```

**Или напрямую через docker-compose:**
```bash
docker-compose up -d
```

### 3. Проверка статуса

```bash
# Статус контейнера
docker-compose ps

# Логи в реальном времени
docker-compose logs -f

# Последние 100 строк логов
docker-compose logs --tail=100
```

### 4. Остановка

**Linux/Mac:**
```bash
./stop.sh
```

**Windows:**
```cmd
stop.bat
```

**Или напрямую:**
```bash
docker-compose down
```

## 🏗️ Dockerfile

### Основные особенности:

- **Базовый образ:** `python:3.11-slim` (легкий, ~150MB)
- **Рабочая директория:** `/app`
- **Volumes:** 
  - `/app/data` - пользовательские данные (users.json, .encryption_key)
  - `/app/logs` - логи бота
  - `/app/temp_documents` - временные файлы
- **Healthcheck:** Проверка работоспособности каждые 30 секунд
- **Multi-stage build:** Нет (можно добавить для уменьшения размера)

### Сборка образа вручную:

```bash
# Сборка
docker build -t buh_bot:latest .

# Запуск
docker run -d \
  --name buh_bot \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  -v $(pwd)/temp_documents:/app/temp_documents \
  buh_bot:latest
```

## 🎛️ Docker Compose

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

```yaml
version: '3.8'

services:
  buh_bot:
    build: .
    container_name: buh_bot
    restart: unless-stopped
    
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - MOYSKLAD_API_URL=${MOYSKLAD_API_URL}
      - TZ=Europe/Moscow
    
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      - ./temp_documents:/app/temp_documents
    
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
```

### Полезные команды:

```bash
# Пересборка образа
docker-compose build --no-cache

# Запуск с выводом логов
docker-compose up

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

# Остановка и удаление контейнера
docker-compose down

# Остановка + удаление volumes
docker-compose down -v

# Просмотр логов конкретного сервиса
docker-compose logs buh_bot

# Вход в контейнер
docker-compose exec buh_bot bash

# Просмотр использования ресурсов
docker stats buh_bot
```

## 📁 Volumes и данные

### Bind Mounts (текущая конфигурация)

Данные хранятся на хосте в директориях:
- `./data/` → `/app/data` - users.json, .encryption_key
- `./logs/` → `/app/logs` - логи бота
- `./temp_documents/` → `/app/temp_documents` - временные документы

**Преимущества:**
- Простой доступ к данным с хоста
- Легко делать backup
- Данные сохраняются после `docker-compose down`

**Backup:**
```bash
# Создание backup
tar -czf backup-$(date +%Y%m%d).tar.gz data/ logs/

# Восстановление
tar -xzf backup-20250103.tar.gz
```

### Named Volumes (альтернатива)

В `docker-compose.yml` можно использовать named volumes:

```yaml
volumes:
  - bot_data:/app/data
  - bot_logs:/app/logs

volumes:
  bot_data:
    driver: local
  bot_logs:
    driver: local
```

**Преимущества:**
- Управляются Docker
- Лучшая производительность на Windows/Mac

**Backup named volumes:**
```bash
# Создание backup
docker run --rm -v bot_data:/data -v $(pwd):/backup \
  alpine tar czf /backup/data-backup.tar.gz -C /data .

# Восстановление
docker run --rm -v bot_data:/data -v $(pwd):/backup \
  alpine tar xzf /backup/data-backup.tar.gz -C /data
```

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

### Environment Variables

**Важно:** Никогда не коммитьте `.env` в Git!

```bash
# .env должен быть в .gitignore
echo ".env" >> .gitignore
```

### Секреты (для продакшена)

Для production рекомендуется использовать Docker secrets:

```yaml
services:
  buh_bot:
    secrets:
      - telegram_token
      
secrets:
  telegram_token:
    file: ./secrets/telegram_token.txt
```

### Ключ шифрования

Критически важно сохранить `.encryption_key`!

```bash
# Backup ключа
cp data/.encryption_key data/.encryption_key.backup

# Или в безопасное место
cp data/.encryption_key ~/secure-backup/
```

Если ключ будет утерян, все пользовательские credentials станут недоступны.

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

### Логи

```bash
# Все логи
docker-compose logs

# Последние 100 строк
docker-compose logs --tail=100

# Следить за логами
docker-compose logs -f

# Логи с временными метками
docker-compose logs -t
```

### Ресурсы

```bash
# Использование CPU/RAM в реальном времени
docker stats buh_bot

# Информация о контейнере
docker inspect buh_bot

# Процессы внутри контейнера
docker-compose top
```

### Healthcheck

Контейнер проверяет свою работоспособность каждые 30 секунд:

```bash
# Проверка health status
docker inspect --format='{{.State.Health.Status}}' buh_bot
```

Статусы:
- `healthy` - всё работает
- `unhealthy` - проблемы (3 неудачных проверки)
- `starting` - контейнер запускается

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

### Обновление кода

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

# Получение обновлений
git pull

# Пересборка образа
docker-compose build

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

### Обновление зависимостей

После изменения `requirements.txt`:

```bash
docker-compose build --no-cache
docker-compose up -d
```

## 🐛 Troubleshooting

### Контейнер не запускается

```bash
# Проверить логи
docker-compose logs

# Проверить конфигурацию
docker-compose config

# Запустить в foreground режиме
docker-compose up
```

### Проблемы с правами доступа

**Linux:**
```bash
# Изменить владельца директорий
sudo chown -R $USER:$USER data logs temp_documents

# Или дать полные права (не рекомендуется для продакшена)
chmod -R 777 data logs temp_documents
```

### Ошибка "port already in use"

Если используются дополнительные сервисы с портами:
```bash
# Найти процесс использующий порт
netstat -tulpn | grep :8443

# Или
lsof -i :8443

# Остановить конфликтующий контейнер
docker stop <container_name>
```

### Контейнер падает с OOM (Out of Memory)

Увеличить лимит памяти в `docker-compose.yml`:
```yaml
deploy:
  resources:
    limits:
      memory: 1G  # было 512M
```

### Нет места на диске

```bash
# Очистка неиспользуемых образов
docker image prune -a

# Очистка всего неиспользуемого
docker system prune -a --volumes

# Проверка использования места
docker system df
```

## 🚀 Production Deployment

### Использование Docker Swarm

```bash
# Инициализация Swarm
docker swarm init

# Деплой stack
docker stack deploy -c docker-compose.yml buh_bot_stack

# Масштабирование (если нужно)
docker service scale buh_bot_stack_buh_bot=2

# Просмотр сервисов
docker stack services buh_bot_stack

# Удаление stack
docker stack rm buh_bot_stack
```

### Использование с nginx (reverse proxy)

Если планируется использовать webhook режим:

```yaml
# docker-compose.yml
services:
  buh_bot:
    # ... существующая конфигурация
    expose:
      - "8443"
    
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
```

### CI/CD пример (GitHub Actions)

```yaml
# .github/workflows/deploy.yml
name: Deploy Bot

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Build and push Docker image
        run: |
          docker build -t myregistry/buh_bot:latest .
          docker push myregistry/buh_bot:latest
      
      - name: Deploy to server
        run: |
          ssh user@server "cd /app/buh_bot && \
            docker-compose pull && \
            docker-compose up -d"
```

## 📚 Дополнительные ресурсы

- [Docker Documentation](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/)
- [Docker security best practices](https://docs.docker.com/engine/security/)

## 🎯 Checklist перед деплоем

- [ ] `.env` файл создан и заполнен
- [ ] `TELEGRAM_BOT_TOKEN` указан корректно
- [ ] Директории `data/`, `logs/`, `temp_documents/` созданы
- [ ] Docker и Docker Compose установлены
- [ ] Backup `.encryption_key` сделан
- [ ] Логирование настроено
- [ ] Healthcheck работает
- [ ] Тестовый запуск выполнен успешно