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:

# Клонируем репозиторий
git clone <repo_url>
cd BUH_bot

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

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

Windows:

git clone <repo_url>
cd BUH_bot

copy .env.example .env
notepad .env

2. Запуск

Linux/Mac:

chmod +x start.sh stop.sh
./start.sh

Windows:

start.bat

Или напрямую через docker-compose:

docker-compose up -d

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

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

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

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

4. Остановка

Linux/Mac:

./stop.sh

Windows:

stop.bat

Или напрямую:

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: Нет (можно добавить для уменьшения размера)

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

# Сборка
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

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

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

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

# Пересборка образа
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:

# Создание 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:

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

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

Преимущества:

• Управляются Docker
• Лучшая производительность на Windows/Mac

Backup named volumes:

# Создание 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!

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

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

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

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

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

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

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

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

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

📊 Мониторинг

Логи

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

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

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

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

Ресурсы

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

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

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

Healthcheck

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

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

Статусы:

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

🔄 Обновление

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

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

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

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

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

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

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

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

🐛 Troubleshooting

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

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

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

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

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

Linux:

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

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

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

Если используются дополнительные сервисы с портами:

# Найти процесс использующий порт
netstat -tulpn | grep :8443

# Или
lsof -i :8443

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

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

Увеличить лимит памяти в docker-compose.yml:

deploy:
  resources:
    limits:
      memory: 1G  # было 512M

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

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

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

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

🚀 Production Deployment

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

# Инициализация 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 режим:

# 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)

# .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
• Docker Compose Documentation
• Best practices for writing Dockerfiles
• Docker security best practices

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

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