Переписана документация

2025-10-29 14:47:35 +03:00
parent e466f14d49
commit e4e23b88ca
10 changed files with 2528 additions and 403 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,122 @@
+# 📚 Документация проекта
+
+Добро пожаловать в документацию Universal Docker & Git Management Project! Здесь вы найдете подробные инструкции по использованию всех компонентов проекта.
+
+## 📖 Содержание
+
+### [📦 Установка зависимостей](installation.md)
+Полное руководство по установке всех необходимых компонентов на различных операционных системах.
+
+**Содержит:**
+- Установка Docker, Make, Git
+- Настройка для Linux, macOS, Windows
+- Устранение проблем установки
+- Проверка корректности установки
+
+### [🐳 Dockerfile](dockerfile.md)
+Подробное описание универсального Dockerfile и способы его настройки.
+
+**Содержит:**
+- Структура и особенности Dockerfile
+- Способы расширения и настройки
+- Оптимизация и безопасность
+- Примеры использования
+
+### [⚙️ Makefile](makefile.md)
+Полное описание команд и переменных Makefile.
+
+**Содержит:**
+- Все команды Docker и Git
+- Подробное описание переменных
+- Настройка и конфигурация
+- Служебные функции
+
+### [📖 Примеры использования](examples.md)
+Практические примеры и сценарии использования проекта.
+
+**Содержит:**
+- Базовая сборка и публикация
+- Мультиплатформенная сборка
+- Оффлайн деплой
+- Работа с аргументами сборки
+- Отладка и мониторинг
+
+### [💡 Лучшие практики](best-practices.md)
+Рекомендации по эффективному использованию проекта.
+
+**Содержит:**
+- Управление версиями
+- Безопасность
+- Оптимизация сборки
+- Мониторинг и логирование
+- Организация проекта
+
+### [🐛 Решение проблем](troubleshooting.md)
+Диагностика и решение частых проблем.
+
+**Содержит:**
+- Частые ошибки и их решения
+- Проблемы с памятью, сетью, правами
+- Диагностические команды
+- Получение помощи
+
+### [❓ FAQ](faq.md)
+Ответы на часто задаваемые вопросы.
+
+**Содержит:**
+- Общие вопросы
+- Вопросы по Docker, Makefile, Git
+- Вопросы по производительности
+- Вопросы по безопасности и отладке
+
+## 🚀 Быстрый старт
+
+1. **Начните с [установки](installation.md)** - установите все необходимые компоненты
+2. **Изучите [Dockerfile](dockerfile.md)** - поймите структуру базового образа
+3. **Ознакомьтесь с [Makefile](makefile.md)** - изучите доступные команды
+4. **Попробуйте [примеры](examples.md)** - выполните практические сценарии
+5. **Следуйте [лучшим практикам](best-practices.md)** - оптимизируйте использование
+
+## 🔍 Поиск по документации
+
+### По задачам
+- **Установка:** [installation.md](installation.md)
+- **Сборка образов:** [dockerfile.md](dockerfile.md), [examples.md](examples.md)
+- **Настройка:** [makefile.md](makefile.md)
+- **Отладка:** [troubleshooting.md](troubleshooting.md)
+
+### По компонентам
+- **Docker:** [dockerfile.md](dockerfile.md), [examples.md](examples.md)
+- **Make:** [makefile.md](makefile.md)
+- **Git:** [makefile.md](makefile.md), [examples.md](examples.md)
+
+### По уровням сложности
+- **Начинающий:** [installation.md](installation.md), [examples.md](examples.md)
+- **Средний:** [dockerfile.md](dockerfile.md), [makefile.md](makefile.md)
+- **Продвинутый:** [best-practices.md](best-practices.md), [troubleshooting.md](troubleshooting.md)
+
+## 📝 Обновления документации
+
+Документация регулярно обновляется. Последние изменения:
+
+- **v2.0** - Полная реструктуризация документации
+- **v1.5** - Добавлены примеры для Windows
+- **v1.0** - Первоначальная версия
+
+## 🤝 Вклад в документацию
+
+Если вы нашли ошибку или хотите улучшить документацию:
+
+1. Создайте [Issue](https://github.com/your-repo/issues) с описанием проблемы
+2. Предложите изменения через Pull Request
+3. Свяжитесь с автором: devops@devops.org.ru
+
+## 📞 Поддержка
+
+- **Email:** devops@devops.org.ru
+- **Сайт:** https://devops.org.ru
+- **Issues:** [GitHub Issues](https://github.com/your-repo/issues)
+
+---
+
+**Спасибо за использование нашего проекта! 🚀**
--- a/docs/best-practices.md
+++ b/docs/best-practices.md
@@ -0,0 +1,353 @@
+# 💡 Лучшие практики
+
+## 1. Управление версиями
+
+### Семантическое версионирование
+```bash
+# Основные версии
+TAG=v1.0.0    # Стабильная версия
+TAG=v1.1.0    # Новая функциональность
+TAG=v1.1.1    # Исправления ошибок
+
+# Предварительные версии
+TAG=v1.2.0-alpha.1
+TAG=v1.2.0-beta.1
+TAG=v1.2.0-rc.1
+
+# Специальные теги
+TAG=latest    # Последняя стабильная
+TAG=dev       # Разработка
+TAG=stable    # Стабильная ветка
+```
+
+### Автоматическое версионирование
+```bash
+# Использование Git commit hash
+TAG=$(git rev-parse --short HEAD)
+
+# Использование даты
+TAG=$(date +%Y%m%d-%H%M%S)
+
+# Использование Git тегов
+TAG=$(git describe --tags --always)
+```
+
+## 2. Безопасность
+
+### Использование непривилегированного пользователя
+```dockerfile
+# В Dockerfile
+RUN useradd -ms /bin/bash appuser
+USER appuser
+```
+
+### Сканирование образов
+```bash
+# Проверка уязвимостей
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image myapp:latest
+
+# Проверка с детальным отчетом
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image --severity HIGH,CRITICAL myapp:latest
+```
+
+## 3. Оптимизация сборки
+
+### Многоэтапная сборка
+```dockerfile
+# Build stage
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Production stage
+FROM node:18-alpine AS production
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+CMD ["npm", "start"]
+```
+
+### Использование .dockerignore
+```dockerfile
+# .dockerignore
+node_modules
+npm-debug.log
+.git
+.gitignore
+README.md
+.env
+.nyc_output
+coverage
+.nyc_output
+.coverage
+```
+
+## 4. Мониторинг и логирование
+
+### Структурированные логи
+```bash
+# Создание логов с метаданными
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  BUILD_ARGS="--build-arg BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  LOG_DIR=./build-logs
+```
+
+### Мониторинг размера образов
+```bash
+# Просмотр размера образа
+docker images myapp:latest
+
+# Детальная информация
+docker history myapp:latest
+
+# Анализ слоев
+docker run --rm -it \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  wagoodman/dive:latest myapp:latest
+```
+
+## 5. Оптимизация производительности
+
+### Кэширование слоев Docker
+```bash
+# Сборка с использованием кэша
+make docker build IMAGE=myapp TAG=v1.0.0
+
+# Сборка без кэша (для чистых сборок)
+make docker build IMAGE=myapp TAG=v1.0.0 NO_CACHE=1
+
+# Принудительное обновление базовых образов
+make docker build IMAGE=myapp TAG=v1.0.0 PULL=1
+```
+
+### Параллельная сборка
+```bash
+# Сборка нескольких образов параллельно
+make docker build IMAGE=frontend TAG=v1.0.0 &
+make docker build IMAGE=backend TAG=v1.0.0 &
+make docker build IMAGE=worker TAG=v1.0.0 &
+wait
+
+# Проверка результатов
+docker images | grep -E "(frontend|backend|worker)"
+```
+
+### Оптимизация размера образов
+```bash
+# Сборка с минимальным размером
+make docker build \
+  IMAGE=myapp \
+  TAG=minimal \
+  BUILD_ARGS="--build-arg BUILDKIT_INLINE_CACHE=1"
+
+# Сжатие образов
+make docker save \
+  SRC_IMAGE=myapp:latest \
+  COMPRESS=1
+```
+
+## 6. Управление зависимостями
+
+### Создание базового образа
+```bash
+# Сборка базового образа
+make docker build \
+  IMAGE=base-image \
+  TAG=ubuntu-22.04 \
+  DOCKERFILE=Dockerfile.base
+
+# Использование базового образа
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  BUILD_ARGS="--build-arg BASE_IMAGE=base-image:ubuntu-22.04"
+```
+
+### Управление зависимостями
+```bash
+# Обновление базовых образов
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  PULL=1
+
+# Проверка обновлений
+docker pull ubuntu:22.04
+```
+
+## 7. Отладка и тестирование
+
+### Тестирование образов
+```bash
+# Запуск тестов в контейнере
+make docker check RUN_CMD="npm test"
+
+# Проверка конфигурации
+make docker check RUN_CMD="nginx -t"
+
+# Проверка портов
+make docker check RUN_CMD="netstat -tlnp"
+```
+
+### Интерактивная отладка
+```bash
+# Запуск интерактивного контейнера
+docker run -it --rm myapp:latest /bin/bash
+
+# Запуск с отладкой
+docker run -it --rm \
+  -p 8080:8080 \
+  -e DEBUG=1 \
+  myapp:latest
+```
+
+## 8. Мониторинг производительности
+
+### Измерение времени сборки
+```bash
+# Время сборки
+time make docker build IMAGE=myapp TAG=v1.0.0
+
+# Детальная статистика
+make docker build IMAGE=myapp TAG=v1.0.0 2>&1 | tee build.log
+```
+
+### Мониторинг ресурсов
+```bash
+# Использование ресурсов контейнеров
+docker stats --no-stream myapp-container
+
+# Анализ размера образов
+docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
+```
+
+## 9. Организация проекта
+
+### Структура файлов
+```
+project/
+├── Dockerfile
+├── makefile
+├── .dockerignore
+├── build.args
+├── Makefile.local
+├── docs/
+│   ├── installation.md
+│   ├── dockerfile.md
+│   ├── makefile.md
+│   ├── examples.md
+│   └── best-practices.md
+├── logs/
+├── images/
+└── .offline/
+```
+
+### Управление конфигурацией
+```bash
+# Создание Makefile.local для проекта
+cat > Makefile.local << EOF
+REGISTRY=my-registry.com
+IMAGE=my-project
+TAG=dev
+NO_CACHE=0
+QUIET=0
+EOF
+
+# Использование конфигурации
+make docker build  # Использует настройки из Makefile.local
+```
+
+## 10. Резервное копирование
+
+### Регулярное сохранение образов
+```bash
+# Создание скрипта для ежедневного бэкапа
+cat > backup.sh << 'EOF'
+#!/bin/bash
+DATE=$(date +%Y%m%d)
+make docker save \
+  SRC_IMAGE=myapp:latest \
+  IMAGES_DIR=/backup/docker-images \
+  COMPRESS=1
+EOF
+
+chmod +x backup.sh
+
+# Добавление в crontab
+echo "0 2 * * * /path/to/backup.sh" | crontab -
+```
+
+### Восстановление из архива
+```bash
+# Восстановление образа
+make docker load \
+  ARCHIVE=/backup/docker-images/myapp_latest.tar.gz \
+  REGISTRY=my-registry.com \
+  IMAGE=myapp \
+  TAG=restored \
+  LOGIN=1 \
+  PUSH_OFFLINE=1
+```
+
+## 11. Документирование
+
+### Создание README для проекта
+```bash
+# Создание документации проекта
+cat > PROJECT_README.md << 'EOF'
+# My Project
+
+## Быстрый старт
+```bash
+make docker build IMAGE=myapp TAG=latest
+make docker push IMAGE=myapp TAG=latest
+```
+
+## Переменные окружения
+- VERSION: Версия приложения
+- NODE_ENV: Окружение (development/production)
+EOF
+```
+
+### Комментирование Dockerfile
+```dockerfile
+# Базовый образ Ubuntu 22.04
+ARG BASE_IMAGE=ubuntu:22.04
+FROM ${BASE_IMAGE}
+
+# Метаданные образа
+LABEL maintainer="Sergey Antropov <devops@devops.org.ru>" \
+      description="Универсальный базовый образ" \
+      version="1.0"
+
+# Настройки окружения для неинтерактивной установки
+ENV DEBIAN_FRONTEND=noninteractive \
+    TZ=Etc/UTC \
+    LANG=C.UTF-8
+
+# Установка необходимых утилит
+RUN apt-get update && \
+    apt-get install -y \
+        ca-certificates \
+        curl \
+        wget \
+        bash \
+        tzdata \
+        nano \
+        mc \
+        tar \
+        gzip \
+        unzip \
+        net-tools \
+        iputils-ping && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Установка рабочей директории
+WORKDIR /app
+```
--- a/docs/dockerfile.md
+++ b/docs/dockerfile.md
@@ -0,0 +1,222 @@
+# 🐳 Dockerfile
+
+## Особенности
+
+- **Базовый образ:** Ubuntu 22.04 (настраивается через ARG)
+- **Предустановленные утилиты:** curl, wget, nano, mc, net-tools, ping и др.
+- **Оптимизированный размер:** удаление кэша apt после установки
+- **Безопасность:** возможность создания непривилегированного пользователя
+- **Гибкость:** легко расширяется под конкретные нужды
+
+## Использование
+
+```bash
+# Сборка с базовым образом Ubuntu 22.04
+make docker build IMAGE=myapp TAG=latest
+
+# Сборка с другим базовым образом
+make docker build IMAGE=myapp TAG=latest BUILD_ARGS="--build-arg BASE_IMAGE=ubuntu:20.04"
+
+# Сборка без кэша
+make docker build IMAGE=myapp TAG=latest NO_CACHE=1
+```
+
+## Структура Dockerfile
+
+```dockerfile
+# Базовый образ (настраивается)
+ARG BASE_IMAGE=ubuntu:22.04
+FROM ${BASE_IMAGE}
+
+# Метаданные
+LABEL maintainer="Sergey Antropov <devops@devops.org.ru>"
+
+# Настройки окружения
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Etc/UTC
+ENV LANG=C.UTF-8
+
+# Установка утилит
+RUN apt-get update && apt-get install -y \
+    ca-certificates curl wget bash tzdata \
+    nano mc tar gzip unzip net-tools \
+    iputils-ping && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Рабочая директория
+WORKDIR /app
+```
+
+## Расширение Dockerfile
+
+### Добавление пользователя
+```dockerfile
+# Создание непривилегированного пользователя
+RUN useradd -ms /bin/bash appuser && \
+    chown -R appuser:appuser /app
+USER appuser
+```
+
+### Добавление портов
+```dockerfile
+# Открытие портов
+EXPOSE 8080
+EXPOSE 3000
+```
+
+### Добавление переменных окружения
+```dockerfile
+# Переменные для приложения
+ENV APP_HOME=/app
+ENV PATH="$PATH:/app/bin"
+ENV NODE_ENV=production
+```
+
+### Добавление команды по умолчанию
+```dockerfile
+# Команда по умолчанию
+CMD ["bash"]
+# или
+CMD ["npm", "start"]
+```
+
+## Примеры использования
+
+### Базовое использование
+```bash
+# Простая сборка
+make docker build IMAGE=myapp TAG=latest
+
+# Сборка с проверкой
+make docker build IMAGE=myapp TAG=v1.0.0
+make docker check RUN_CMD="lsb_release -a"
+```
+
+### Сборка с аргументами
+```bash
+# Передача переменных в Dockerfile
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  BUILD_ARGS="--build-arg VERSION=1.0.0 --build-arg NODE_ENV=production"
+```
+
+### Сборка с файлом аргументов
+```bash
+# Создание файла build.args
+cat > build.args << EOF
+VERSION=1.0.0
+BUILD_DATE=2024-01-15
+NODE_ENV=production
+EOF
+
+# Сборка с файлом аргументов
+make docker build IMAGE=myapp TAG=v1.0.0 ARG_FILE=build.args
+```
+
+## Оптимизация Dockerfile
+
+### Многоэтапная сборка
+```dockerfile
+# Build stage
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Production stage
+FROM node:18-alpine AS production
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+CMD ["npm", "start"]
+```
+
+### Использование .dockerignore
+```dockerfile
+# .dockerignore
+node_modules
+npm-debug.log
+.git
+.gitignore
+README.md
+.env
+.nyc_output
+coverage
+```
+
+### Минимизация слоев
+```dockerfile
+# Плохо - много слоев
+RUN apt-get update
+RUN apt-get install -y curl
+RUN apt-get install -y wget
+RUN apt-get clean
+
+# Хорошо - один слой
+RUN apt-get update && \
+    apt-get install -y curl wget && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+## Безопасность
+
+### Использование непривилегированного пользователя
+```dockerfile
+# Создание пользователя
+RUN useradd -ms /bin/bash appuser
+USER appuser
+```
+
+### Сканирование уязвимостей
+```bash
+# Проверка уязвимостей
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image myapp:latest
+
+# Проверка с детальным отчетом
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image --severity HIGH,CRITICAL myapp:latest
+```
+
+### Обновление пакетов
+```dockerfile
+# Обновление всех пакетов
+RUN apt-get update && \
+    apt-get upgrade -y && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+## Отладка
+
+### Просмотр истории сборки
+```bash
+# История слоев
+docker history myapp:latest
+
+# Детальная информация
+docker image inspect myapp:latest
+```
+
+### Интерактивная отладка
+```bash
+# Запуск интерактивного контейнера
+docker run -it --rm myapp:latest /bin/bash
+
+# Запуск с отладкой
+docker run -it --rm \
+  -p 8080:8080 \
+  -e DEBUG=1 \
+  myapp:latest
+```
+
+### Анализ размера образа
+```bash
+# Анализ слоев
+docker run --rm -it \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  wagoodman/dive:latest myapp:latest
+```
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -0,0 +1,346 @@
+# 📖 Примеры использования
+
+## 1. Базовая сборка и публикация
+
+### Простая сборка
+```bash
+# Сборка с минимальными параметрами
+make docker build IMAGE=myapp TAG=latest
+
+# Сборка с кастомным registry
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  REGISTRY=hub.cism-ms.ru/library
+
+# Сборка с проверкой
+make docker build IMAGE=myapp TAG=v1.0.0
+make docker check RUN_CMD="lsb_release -a"
+```
+
+### Полный цикл сборки и публикации
+```bash
+# 1. Сборка образа
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  REGISTRY=hub.cism-ms.ru/library
+
+# 2. Проверка работоспособности
+make docker check \
+  RUN_CMD="curl -f http://localhost:8080/health"
+
+# 3. Публикация в registry
+make docker push \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  REGISTRY=hub.cism-ms.ru/library
+```
+
+## 2. Мультиплатформенная сборка
+
+### Настройка buildx
+```bash
+# Создание buildx builder
+make docker create-builder
+
+# Проверка builder'а
+make docker use-builder
+
+# Просмотр доступных платформ
+docker buildx inspect --bootstrap
+```
+
+### Сборка для нескольких платформ
+```bash
+# Сборка для AMD64 и ARM64
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  USE_BUILDX=1 \
+  PLATFORMS="linux/amd64,linux/arm64" \
+  PUSH=1 \
+  LOAD=0
+
+# Сборка для всех популярных платформ
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  USE_BUILDX=1 \
+  PLATFORMS="linux/amd64,linux/arm64,linux/arm/v7" \
+  PUSH=1
+```
+
+## 3. Оффлайн деплой
+
+### Сохранение образов
+```bash
+# Простое сохранение
+make docker save SRC_IMAGE=myapp:latest
+
+# Сохранение с сжатием
+make docker save \
+  SRC_IMAGE=myapp:v1.0.0 \
+  COMPRESS=1
+
+# Сохранение с разбиением на части
+make docker save \
+  SRC_IMAGE=myapp:v1.0.0 \
+  COMPRESS=1 \
+  SPLIT_SIZE=2G
+
+# Сохранение в кастомную директорию
+make docker save \
+  SRC_IMAGE=myapp:v1.0.0 \
+  IMAGES_DIR=/backup/containers \
+  COMPRESS=1
+```
+
+### Загрузка и публикация
+```bash
+# Простая загрузка
+make docker load ARCHIVE=images/myapp_v1.0.0.tar.gz
+
+# Загрузка с авторизацией и публикацией
+make docker load \
+  ARCHIVE=images/myapp_v1.0.0.tar.gz \
+  REGISTRY=hub.cism-ms.ru/library \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  LOGIN=1 \
+  PUSH_OFFLINE=1
+
+# Загрузка с сохранением исходного тега
+make docker load \
+  ARCHIVE=images/myapp_v1.0.0.tar.gz \
+  KEEP_SRC_TAG=1 \
+  LOGIN=1 \
+  PUSH_OFFLINE=1
+```
+
+## 4. Работа с аргументами сборки
+
+### Использование BUILD_ARGS
+```bash
+# Передача переменных окружения
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  BUILD_ARGS="--build-arg VERSION=1.0.0 --build-arg NODE_ENV=production"
+
+# Передача пользовательских данных
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  BUILD_ARGS="--build-arg USER_ID=1000 --build-arg GROUP_ID=1000"
+```
+
+### Использование ARG_FILE
+```bash
+# Создание файла с аргументами
+cat > build.args << EOF
+VERSION=1.0.0
+BUILD_DATE=2024-01-15
+GIT_COMMIT=abc123def
+NODE_ENV=production
+USER_ID=1000
+GROUP_ID=1000
+EOF
+
+# Сборка с файлом аргументов
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  ARG_FILE=build.args
+```
+
+## 5. Работа с Git
+
+### Базовые операции
+```bash
+# Просмотр статуса
+make git status
+
+# Получение изменений
+make git pull
+
+# Коммит с сообщением
+make git commit GIT_MSG="Добавлена поддержка Docker"
+
+# Коммит и push
+make git push GIT_MSG="Обновлена документация"
+```
+
+### Продвинутые сценарии
+```bash
+# Синхронизация с удаленным репозиторием
+make git sync
+
+# Работа с разными удаленными репозиториями
+make git pull GIT_REMOTE=upstream
+make git push GIT_REMOTE=origin GIT_MSG="Синхронизация с upstream"
+```
+
+## 6. Работа с разными операционными системами
+
+### Linux (Ubuntu/Debian)
+```bash
+# Установка Docker
+sudo apt-get update
+sudo apt-get install -y docker.io
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker $USER
+
+# Установка Make
+sudo apt-get install -y make
+
+# Перезагрузка для применения изменений группы
+sudo reboot
+```
+
+### Linux (CentOS/RHEL/Fedora)
+```bash
+# Установка Docker
+sudo yum install -y docker
+# или для Fedora
+sudo dnf install -y docker
+
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker $USER
+
+# Установка Make
+sudo yum install -y make
+# или для Fedora
+sudo dnf install -y make
+```
+
+### macOS
+```bash
+# Установка через Homebrew
+brew install docker
+brew install make
+
+# Или установка Docker Desktop
+# Скачайте с https://www.docker.com/products/docker-desktop
+
+# Проверка установки
+docker --version
+make --version
+```
+
+### Windows
+```bash
+# Через WSL2 (рекомендуется)
+wsl --install
+# Затем в WSL2:
+sudo apt-get update
+sudo apt-get install -y docker.io make
+
+# Или через Git Bash
+# Установите Docker Desktop и Git for Windows
+# Make поставляется с Git for Windows
+```
+
+## 7. Отладка и мониторинг
+
+### Просмотр конфигурации
+```bash
+# Показать все переменные
+make docker print-config
+
+# Показать информацию об образе
+make docker inspect
+
+# Просмотр логов сборки
+tail -f logs/build_20240115_143022.log
+```
+
+### Проверка образов
+```bash
+# Проверка версии Java
+make docker check RUN_CMD="java -version"
+
+# Проверка версии Node.js
+make docker check RUN_CMD="node --version"
+
+# Проверка доступности сервиса
+make docker check RUN_CMD="curl -f http://localhost:8080/health"
+
+# Проверка переменных окружения
+make docker check RUN_CMD="env | grep -E 'VERSION|NODE_ENV'"
+```
+
+## 8. Продвинутые сценарии
+
+### Сборка с кастомным Dockerfile
+```bash
+# Сборка с Dockerfile.prod
+make docker build \
+  IMAGE=myapp \
+  TAG=production \
+  DOCKERFILE=Dockerfile.prod
+
+# Сборка с контекстом в подпапке
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  CONTEXT=./app
+```
+
+### Работа с разными registry
+```bash
+# Сборка для локального registry
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  REGISTRY=localhost:5000
+
+# Сборка для Docker Hub
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  REGISTRY=myusername
+
+# Сборка для GitLab Registry
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  REGISTRY=registry.gitlab.com/myproject
+```
+
+### Управление тегами
+```bash
+# Перетегирование образа
+make docker retag NEW_TAG=v2.0.0
+
+# Создание нескольких тегов
+make docker retag NEW_TAG=latest
+make docker retag NEW_TAG=stable
+make docker retag NEW_TAG=2024.01.15
+```
+
+## 9. Очистка и обслуживание
+
+### Очистка временных файлов
+```bash
+# Очистка логов и временных файлов
+make docker clean
+
+# Очистка Docker системы (вручную)
+docker system prune -f
+docker image prune -f
+```
+
+### Управление архивами
+```bash
+# Просмотр сохраненных архивов
+ls -la images/
+
+# Проверка целостности архива
+sha256sum -c images/myapp_v1.0.0.tar.gz.sha256
+
+# Удаление старых архивов
+find images/ -name "*.tar.gz" -mtime +30 -delete
+```
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -0,0 +1,368 @@
+# ❓ FAQ (Часто задаваемые вопросы)
+
+## Общие вопросы
+
+### Q: Как использовать Makefile в Windows?
+**A:** Установите WSL2 или используйте Git Bash:
+```bash
+# В Git Bash
+make docker build IMAGE=myapp TAG=latest
+
+# Или через WSL2
+wsl make docker build IMAGE=myapp TAG=latest
+```
+
+### Q: Можно ли использовать с Docker Compose?
+**A:** Да, можно интегрировать:
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: myapp:latest
+```
+
+### Q: Как настроить автоматическую сборку при коммите?
+**A:** Используйте Git hooks:
+```bash
+# .git/hooks/post-commit
+#!/bin/bash
+make docker build IMAGE=myapp TAG=$(git rev-parse --short HEAD)
+```
+
+### Q: Можно ли использовать с Kubernetes?
+**A:** Да, после сборки образа:
+```bash
+# Сборка образа
+make docker build IMAGE=myapp TAG=v1.0.0
+
+# Применение в Kubernetes
+kubectl apply -f k8s/
+```
+
+### Q: Как оптимизировать время сборки?
+**A:** Используйте кэширование и .dockerignore:
+```bash
+# Сборка с кэшем
+make docker build IMAGE=myapp TAG=v1.0.0
+
+# Создание .dockerignore
+echo "node_modules" >> .dockerignore
+echo ".git" >> .dockerignore
+```
+
+### Q: Как проверить правильность установки?
+**A:** Выполните проверочные команды:
+```bash
+# Проверка Docker
+docker --version
+docker run hello-world
+
+# Проверка Make
+make --version
+
+# Проверка Git
+git --version
+```
+
+## Вопросы по Docker
+
+### Q: Как работать с приватными registry?
+**A:** Настройте авторизацию:
+```bash
+# Авторизация
+make docker login REGISTRY=your-private-registry.com
+
+# Сборка и публикация
+make docker push IMAGE=myapp TAG=v1.0.0 REGISTRY=your-private-registry.com
+```
+
+### Q: Можно ли использовать с ARM процессорами?
+**A:** Да, через buildx:
+```bash
+# Сборка для ARM64
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  USE_BUILDX=1 \
+  PLATFORMS=linux/arm64
+```
+
+### Q: Как мониторить использование ресурсов?
+**A:** Используйте встроенные команды Docker:
+```bash
+# Мониторинг контейнеров
+docker stats
+
+# Анализ образов
+docker history myapp:latest
+```
+
+### Q: Как уменьшить размер образа?
+**A:** Используйте многоэтапную сборку и .dockerignore:
+```dockerfile
+# Многоэтапная сборка
+FROM node:18-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM node:18-alpine AS production
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY . .
+CMD ["npm", "start"]
+```
+
+### Q: Как сканировать образы на уязвимости?
+**A:** Используйте Trivy:
+```bash
+# Сканирование образа
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image myapp:latest
+
+# Сканирование с фильтром по критичности
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image --severity HIGH,CRITICAL myapp:latest
+```
+
+## Вопросы по Makefile
+
+### Q: Как переопределить переменные по умолчанию?
+**A:** Создайте Makefile.local или передайте при вызове:
+```bash
+# Через Makefile.local
+echo "REGISTRY=my-registry.com" > Makefile.local
+
+# Через параметры командной строки
+make docker build IMAGE=myapp TAG=v1.0.0 REGISTRY=my-registry.com
+```
+
+### Q: Как использовать разные Dockerfile для разных окружений?
+**A:** Используйте переменную DOCKERFILE:
+```bash
+# Для разработки
+make docker build IMAGE=myapp TAG=dev DOCKERFILE=Dockerfile.dev
+
+# Для продакшена
+make docker build IMAGE=myapp TAG=prod DOCKERFILE=Dockerfile.prod
+```
+
+### Q: Как передать много аргументов в Docker build?
+**A:** Используйте ARG_FILE:
+```bash
+# Создание файла аргументов
+cat > build.args << EOF
+VERSION=1.0.0
+BUILD_DATE=2024-01-15
+NODE_ENV=production
+USER_ID=1000
+GROUP_ID=1000
+EOF
+
+# Использование файла
+make docker build IMAGE=myapp TAG=v1.0.0 ARG_FILE=build.args
+```
+
+### Q: Как настроить логирование?
+**A:** Используйте переменные LOG_DIR и LOG_FILE:
+```bash
+# Кастомная директория логов
+make docker build IMAGE=myapp TAG=v1.0.0 LOG_DIR=./build-logs
+
+# Просмотр логов
+tail -f logs/build_20240115_143022.log
+```
+
+## Вопросы по Git
+
+### Q: Как работать с разными удаленными репозиториями?
+**A:** Используйте переменную GIT_REMOTE:
+```bash
+# Работа с origin
+make git push GIT_REMOTE=origin GIT_MSG="Обновление"
+
+# Работа с upstream
+make git pull GIT_REMOTE=upstream
+```
+
+### Q: Как автоматизировать коммиты?
+**A:** Используйте переменную GIT_MSG:
+```bash
+# Коммит с сообщением
+make git commit GIT_MSG="Автоматический коммит"
+
+# Push с коммитом
+make git push GIT_MSG="Обновление от $(date)"
+```
+
+### Q: Как синхронизировать с удаленным репозиторием?
+**A:** Используйте команду sync:
+```bash
+# Полная синхронизация (pull + commit + push)
+make git sync
+```
+
+## Вопросы по производительности
+
+### Q: Как ускорить сборку?
+**A:** Используйте кэширование и оптимизацию:
+```bash
+# Сборка с кэшем
+make docker build IMAGE=myapp TAG=v1.0.0
+
+# Параллельная сборка
+make docker build IMAGE=frontend TAG=v1.0.0 &
+make docker build IMAGE=backend TAG=v1.0.0 &
+wait
+```
+
+### Q: Как мониторить время сборки?
+**A:** Используйте команду time:
+```bash
+# Измерение времени сборки
+time make docker build IMAGE=myapp TAG=v1.0.0
+
+# Детальная статистика
+make docker build IMAGE=myapp TAG=v1.0.0 2>&1 | tee build.log
+```
+
+### Q: Как оптимизировать размер образов?
+**A:** Используйте многоэтапную сборку и .dockerignore:
+```bash
+# Сборка с минимальным размером
+make docker build \
+  IMAGE=myapp \
+  TAG=minimal \
+  BUILD_ARGS="--build-arg BUILDKIT_INLINE_CACHE=1"
+```
+
+## Вопросы по безопасности
+
+### Q: Как работать с секретами?
+**A:** Используйте Docker secrets или переменные окружения:
+```bash
+# Через переменные окружения
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  BUILD_ARGS="--build-arg API_KEY=\$API_KEY"
+```
+
+### Q: Как сканировать образы на уязвимости?
+**A:** Используйте Trivy или другие инструменты:
+```bash
+# Сканирование с Trivy
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image myapp:latest
+```
+
+### Q: Как использовать непривилегированного пользователя?
+**A:** Настройте в Dockerfile:
+```dockerfile
+# Создание пользователя
+RUN useradd -ms /bin/bash appuser
+USER appuser
+```
+
+## Вопросы по отладке
+
+### Q: Как отладить сборку?
+**A:** Используйте подробный вывод и логи:
+```bash
+# Подробный вывод
+make docker build IMAGE=myapp TAG=v1.0.0 QUIET=0
+
+# Просмотр логов
+tail -f logs/build_*.log
+
+# Интерактивная отладка
+docker run -it --rm myapp:latest /bin/bash
+```
+
+### Q: Как проверить образ после сборки?
+**A:** Используйте команду check:
+```bash
+# Проверка версии
+make docker check RUN_CMD="node --version"
+
+# Проверка сервиса
+make docker check RUN_CMD="curl -f http://localhost:8080/health"
+```
+
+### Q: Как получить информацию об образе?
+**A:** Используйте команду inspect:
+```bash
+# Детальная информация
+make docker inspect
+
+# История слоев
+docker history myapp:latest
+```
+
+## Вопросы по архивам
+
+### Q: Как создать архив образа?
+**A:** Используйте команду save:
+```bash
+# Простое сохранение
+make docker save SRC_IMAGE=myapp:latest
+
+# С сжатием
+make docker save SRC_IMAGE=myapp:latest COMPRESS=1
+```
+
+### Q: Как загрузить архив образа?
+**A:** Используйте команду load:
+```bash
+# Простая загрузка
+make docker load ARCHIVE=images/myapp.tar
+
+# С публикацией
+make docker load \
+  ARCHIVE=images/myapp.tar \
+  LOGIN=1 \
+  PUSH_OFFLINE=1
+```
+
+### Q: Как разбить архив на части?
+**A:** Используйте переменную SPLIT_SIZE:
+```bash
+# Разбиение на части по 2GB
+make docker save \
+  SRC_IMAGE=myapp:latest \
+  SPLIT_SIZE=2G
+```
+
+## Вопросы по конфигурации
+
+### Q: Как настроить цвета вывода?
+**A:** Используйте переменные цветов:
+```bash
+# Отключение цветов
+make docker build \
+  IMAGE=myapp \
+  TAG=v1.0.0 \
+  COLOR_RESET= \
+  COLOR_INFO= \
+  COLOR_OK= \
+  COLOR_ERR= \
+  COLOR_WARN=
+```
+
+### Q: Как настроить тихий режим?
+**A:** Используйте переменную QUIET:
+```bash
+# Тихий режим
+make docker build IMAGE=myapp TAG=v1.0.0 QUIET=1
+```
+
+### Q: Как настроить кастомную директорию логов?
+**A:** Используйте переменную LOG_DIR:
+```bash
+# Кастомная директория
+make docker build IMAGE=myapp TAG=v1.0.0 LOG_DIR=./custom-logs
+```
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -0,0 +1,196 @@
+# 📦 Установка зависимостей
+
+## Предварительные требования
+
+- Docker (версия 20.10+)
+- Make (GNU Make 3.81+)
+- Git (версия 2.0+)
+
+## Linux (Ubuntu/Debian)
+
+```bash
+# Обновление системы
+sudo apt-get update
+
+# Установка Docker
+sudo apt-get install -y docker.io
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker $USER
+
+# Установка Make
+sudo apt-get install -y make
+
+# Установка Git (если не установлен)
+sudo apt-get install -y git
+
+# Перезагрузка для применения изменений группы
+sudo reboot
+
+# Проверка установки
+docker --version
+make --version
+git --version
+```
+
+## Linux (CentOS/RHEL/Fedora)
+
+```bash
+# Для CentOS/RHEL
+sudo yum install -y docker make git
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker $USER
+
+# Для Fedora
+sudo dnf install -y docker make git
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker $USER
+
+# Проверка установки
+docker --version
+make --version
+git --version
+```
+
+## macOS
+
+### Вариант 1: Через Homebrew (рекомендуется)
+```bash
+# Установка Homebrew (если не установлен)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Установка зависимостей
+brew install docker
+brew install make
+brew install git
+
+# Запуск Docker Desktop
+open /Applications/Docker.app
+
+# Проверка установки
+docker --version
+make --version
+git --version
+```
+
+### Вариант 2: Docker Desktop
+```bash
+# 1. Скачайте Docker Desktop с https://www.docker.com/products/docker-desktop
+# 2. Установите Docker Desktop
+# 3. Установите Make через Homebrew
+brew install make
+
+# Проверка установки
+docker --version
+make --version
+```
+
+## Windows
+
+### Вариант 1: WSL2 (рекомендуется)
+```powershell
+# В PowerShell от имени администратора
+wsl --install
+
+# Перезагрузите компьютер, затем в WSL2:
+sudo apt-get update
+sudo apt-get install -y docker.io make git
+sudo systemctl start docker
+sudo usermod -aG docker $USER
+
+# Проверка установки
+docker --version
+make --version
+git --version
+```
+
+### Вариант 2: Git Bash
+```bash
+# 1. Установите Docker Desktop с https://www.docker.com/products/docker-desktop
+# 2. Установите Git for Windows с https://git-scm.com/download/win
+#    (Make поставляется с Git for Windows)
+
+# Проверка установки в Git Bash
+docker --version
+make --version
+git --version
+```
+
+## Проверка установки
+
+После установки выполните проверку:
+
+```bash
+# Проверка Docker
+docker --version
+docker run hello-world
+
+# Проверка Make
+make --version
+
+# Проверка Git
+git --version
+
+# Проверка прав Docker (Linux/macOS)
+docker ps
+```
+
+## Устранение проблем установки
+
+### Проблема: "docker: command not found"
+```bash
+# Linux
+sudo apt-get update && sudo apt-get install -y docker.io
+
+# macOS
+brew install docker
+
+# Windows
+# Убедитесь, что Docker Desktop запущен
+```
+
+### Проблема: "permission denied while trying to connect to Docker daemon"
+```bash
+# Linux/macOS
+sudo usermod -aG docker $USER
+# Перезагрузите систему или выполните:
+newgrp docker
+```
+
+### Проблема: "make: command not found"
+```bash
+# Ubuntu/Debian
+sudo apt-get install -y make
+
+# CentOS/RHEL
+sudo yum install -y make
+
+# Fedora
+sudo dnf install -y make
+
+# macOS
+brew install make
+
+# Windows
+# Make поставляется с Git for Windows
+```
+
+## Установка проекта
+
+1. **Клонируйте репозиторий:**
+```bash
+git clone <repository-url>
+cd Dockerfile
+```
+
+2. **Проверьте Makefile:**
+```bash
+make help
+```
+
+3. **Проверьте Docker:**
+```bash
+make docker print-config
+```
--- a/docs/makefile.md
+++ b/docs/makefile.md
@@ -0,0 +1,368 @@
+# ⚙️ Makefile
+
+## Основные команды
+
+### Docker команды
+
+| Команда | Описание | Пример |
+|---------|----------|--------|
+| `make docker build` | Собрать Docker-образ | `make docker build IMAGE=myapp TAG=v1.0` |
+| `make docker check` | Проверить образ | `make docker check RUN_CMD="java -version"` |
+| `make docker push` | Собрать + проверить + отправить | `make docker push IMAGE=myapp TAG=v1.0` |
+| `make docker save` | Сохранить образ в архив | `make docker save SRC_IMAGE=myapp:latest` |
+| `make docker load` | Загрузить из архива | `make docker load ARCHIVE=images/myapp.tar` |
+| `make docker login` | Авторизация в registry | `make docker login REGISTRY=hub.cism-ms.ru` |
+| `make docker retag` | Перетегировать образ | `make docker retag NEW_TAG=v2.0` |
+| `make docker inspect` | Просмотреть метаданные | `make docker inspect` |
+| `make docker clean` | Очистить временные файлы | `make docker clean` |
+
+### Git команды
+
+| Команда | Описание | Пример |
+|---------|----------|--------|
+| `make git status` | Показать статус репозитория | `make git status` |
+| `make git pull` | Получить изменения | `make git pull` |
+| `make git commit` | Создать коммит | `make git commit GIT_MSG="Обновление"` |
+| `make git push` | Коммит + push | `make git push GIT_MSG="Новая версия"` |
+| `make git sync` | Pull + commit + push | `make git sync` |
+
+## Подробное описание переменных
+
+### Основные Docker переменные
+
+#### REGISTRY
+**Описание:** Адрес Docker Registry без протокола  
+**По умолчанию:** `hub.cism-ms.ru/library`  
+**Примеры:**
+```bash
+REGISTRY=hub.cism-ms.ru/library
+REGISTRY=registry.gitlab.com/myproject
+REGISTRY=localhost:5000
+```
+
+#### IMAGE
+**Описание:** Имя Docker-образа (обязательное поле при сборке)  
+**По умолчанию:** пустое  
+**Примеры:**
+```bash
+IMAGE=myapp
+IMAGE=web-frontend
+IMAGE=api-backend
+```
+
+#### TAG
+**Описание:** Тег образа  
+**По умолчанию:** `latest`  
+**Примеры:**
+```bash
+TAG=latest
+TAG=v1.0.0
+TAG=dev
+TAG=2024.01.15
+```
+
+#### CONTEXT
+**Описание:** Папка контекста сборки Docker  
+**По умолчанию:** `.` (текущая директория)  
+**Примеры:**
+```bash
+CONTEXT=.
+CONTEXT=./app
+CONTEXT=/path/to/build/context
+```
+
+#### DOCKERFILE
+**Описание:** Имя Dockerfile, используемого при сборке  
+**По умолчанию:** `Dockerfile`  
+**Примеры:**
+```bash
+DOCKERFILE=Dockerfile
+DOCKERFILE=Dockerfile.prod
+DOCKERFILE=./docker/Dockerfile
+```
+
+### Режимы сборки
+
+#### USE_BUILDX
+**Описание:** Использовать Docker Buildx для мультиплатформенной сборки  
+**По умолчанию:** `0`  
+**Значения:**
+- `0` - обычный `docker build`
+- `1` - использовать `docker buildx build`
+
+**Примеры:**
+```bash
+# Обычная сборка
+USE_BUILDX=0
+
+# Мультиплатформенная сборка
+USE_BUILDX=1 PLATFORMS="linux/amd64,linux/arm64"
+```
+
+#### PLATFORMS
+**Описание:** Целевые платформы для buildx (через запятую)  
+**По умолчанию:** `linux/amd64`  
+**Примеры:**
+```bash
+PLATFORMS=linux/amd64
+PLATFORMS=linux/amd64,linux/arm64
+PLATFORMS=linux/amd64,linux/arm64,linux/arm/v7
+```
+
+#### PUSH
+**Описание:** Выполнить docker push после buildx  
+**По умолчанию:** `0`  
+**Значения:**
+- `0` - не выполнять push
+- `1` - выполнить push после сборки
+
+**Примечание:** Работает только с `USE_BUILDX=1`
+
+#### LOAD
+**Описание:** Загрузить образ в локальный docker после сборки  
+**По умолчанию:** `1`  
+**Значения:**
+- `0` - не загружать (актуально для CI/CD)
+- `1` - загрузить в локальный docker
+
+#### NO_CACHE
+**Описание:** Сборка без использования кэша  
+**По умолчанию:** `0`  
+**Значения:**
+- `0` - использовать кэш Docker
+- `1` - сборка без кэша
+
+**Примеры:**
+```bash
+# Сборка с кэшем (быстрее)
+NO_CACHE=0
+
+# Сборка без кэша (медленнее, но чище)
+NO_CACHE=1
+```
+
+#### PULL
+**Описание:** Принудительно обновить базовые образы  
+**По умолчанию:** `0`  
+**Значения:**
+- `0` - использовать локальные образы
+- `1` - принудительно скачать последние версии
+
+#### QUIET
+**Описание:** Минимальный вывод в консоль  
+**По умолчанию:** `0`  
+**Значения:**
+- `0` - стандартный вывод
+- `1` - минимальный вывод (для CI/CD)
+
+### Аргументы сборки
+
+#### BUILD_ARGS
+**Описание:** Дополнительные аргументы для docker build  
+**По умолчанию:** пустое  
+**Формат:** `--build-arg KEY=VALUE --build-arg KEY2=VALUE2`
+
+**Примеры:**
+```bash
+BUILD_ARGS="--build-arg VERSION=1.0.0 --build-arg DEBUG=1"
+BUILD_ARGS="--build-arg NODE_ENV=production"
+BUILD_ARGS="--build-arg USER_ID=1000 --build-arg GROUP_ID=1000"
+```
+
+#### ARG_FILE
+**Описание:** Путь к файлу с переменными KEY=VALUE  
+**По умолчанию:** пустое  
+**Формат файла:** Каждая строка содержит `KEY=VALUE`
+
+**Пример файла `build.args`:**
+```
+VERSION=1.0.0
+BUILD_DATE=2024-01-15
+GIT_COMMIT=abc123def
+NODE_ENV=production
+USER_ID=1000
+GROUP_ID=1000
+```
+
+**Использование:**
+```bash
+make docker build ARG_FILE=build.args
+```
+
+### Проверка и логирование
+
+#### RUN_CMD
+**Описание:** Команда для проверки контейнера после сборки  
+**По умолчанию:** `lsb_release -a`  
+**Примеры:**
+```bash
+RUN_CMD="java -version"
+RUN_CMD="node --version"
+RUN_CMD="python3 --version"
+RUN_CMD="curl -f http://localhost:8080/health"
+```
+
+#### BUILDER
+**Описание:** Имя buildx builder'а  
+**По умолчанию:** `universal-builder`  
+**Примеры:**
+```bash
+BUILDER=universal-builder
+BUILDER=my-custom-builder
+BUILDER=ci-builder
+```
+
+#### LOG_DIR
+**Описание:** Каталог для логов сборок  
+**По умолчанию:** `logs`  
+**Примеры:**
+```bash
+LOG_DIR=logs
+LOG_DIR=./build-logs
+LOG_DIR=/var/log/docker-builds
+```
+
+#### LOG_FILE
+**Описание:** Файл лога (формируется автоматически)  
+**По умолчанию:** `$(LOG_DIR)/build_$(shell date +%Y%m%d_%H%M%S).log`  
+**Пример:** `logs/build_20240115_143022.log`
+
+### Оффлайн переменные (SAVE/LOAD)
+
+#### ARCHIVE
+**Описание:** Путь к архиву образа (tar или gz)  
+**По умолчанию:** `image.tar`  
+**Примеры:**
+```bash
+ARCHIVE=image.tar
+ARCHIVE=images/myapp_v1.0.0.tar.gz
+ARCHIVE=/backup/containers/myapp.tar
+```
+
+#### IMAGES_DIR
+**Описание:** Каталог для сохранения архивов Docker-образов  
+**По умолчанию:** `images`  
+**Примеры:**
+```bash
+IMAGES_DIR=images
+IMAGES_DIR=./docker-images
+IMAGES_DIR=/backup/containers
+```
+
+#### SRC_IMAGE
+**Описание:** Имя исходного образа для сохранения  
+**По умолчанию:** `$(FULL_IMAGE)` если IMAGE задан  
+**Примеры:**
+```bash
+SRC_IMAGE=myapp:latest
+SRC_IMAGE=ubuntu:22.04
+SRC_IMAGE=registry.local/myapp:v1.0
+```
+
+#### COMPRESS
+**Описание:** Сжать архив gzip  
+**По умолчанию:** `0`  
+**Значения:**
+- `0` - оставить tar
+- `1` - сжать gzip
+
+**Примеры:**
+```bash
+# Сохранить как tar
+make docker save SRC_IMAGE=myapp:latest COMPRESS=0
+
+# Сохранить как tar.gz
+make docker save SRC_IMAGE=myapp:latest COMPRESS=1
+```
+
+#### SPLIT_SIZE
+**Описание:** Размер чанка для разбиения архива  
+**По умолчанию:** пустое (не разбивать)  
+**Примеры:**
+```bash
+SPLIT_SIZE=2G    # Разбить на части по 2GB
+SPLIT_SIZE=1G    # Разбить на части по 1GB
+SPLIT_SIZE=500M  # Разбить на части по 500MB
+```
+
+#### LOGIN
+**Описание:** Выполнить docker login перед push  
+**По умолчанию:** `1`  
+**Значения:**
+- `0` - пропустить авторизацию
+- `1` - выполнить docker login
+
+#### PUSH_OFFLINE
+**Описание:** Выполнить docker push после загрузки архива  
+**По умолчанию:** `1`  
+**Значения:**
+- `0` - только загрузить
+- `1` - загрузить и запушить
+
+#### KEEP_SRC_TAG
+**Описание:** Использовать тег из архива  
+**По умолчанию:** `1`  
+**Значения:**
+- `0` - использовать TAG из Makefile
+- `1` - использовать тег из загруженного архива
+
+#### OFFLINE_DIR
+**Описание:** Временная служебная папка для оффлайн операций  
+**По умолчанию:** `.offline`  
+**Содержит:** `load.log`, `src_image.txt`, `dst_image.txt`, `last_save.txt`
+
+#### LAST_SAVE
+**Описание:** Путь к последнему сохранённому архиву  
+**По умолчанию:** `$(OFFLINE_DIR)/last_save.txt`
+
+### Git переменные
+
+#### GIT_REMOTE
+**Описание:** Имя удалённого репозитория  
+**По умолчанию:** `origin`  
+**Примеры:**
+```bash
+GIT_REMOTE=origin
+GIT_REMOTE=upstream
+GIT_REMOTE=backup
+```
+
+#### GIT_BRANCH
+**Описание:** Текущая ветка (определяется автоматически)  
+**По умолчанию:** `$(shell git rev-parse --abbrev-ref HEAD)`  
+**Примеры:** `main`, `develop`, `feature/new-feature`
+
+#### GIT_MSG
+**Описание:** Сообщение коммита  
+**По умолчанию:** запрашивается вручную  
+**Примеры:**
+```bash
+GIT_MSG="Добавлена поддержка Docker"
+GIT_MSG="Исправлена ошибка в сборке"
+GIT_MSG="Обновлены зависимости"
+```
+
+### Служебные переменные
+
+#### FULL_IMAGE
+**Описание:** Полное имя образа REGISTRY/IMAGE:TAG  
+**Формируется автоматически:** `$(REGISTRY)/$(IMAGE):$(TAG)`  
+**Примеры:**
+```bash
+FULL_IMAGE=hub.cism-ms.ru/library/myapp:latest
+FULL_IMAGE=registry.local/myapp:v1.0.0
+```
+
+#### Цвета вывода
+**Описание:** ANSI-коды для форматирования вывода  
+**Переменные:**
+- `COLOR_RESET` - сброс цвета
+- `COLOR_INFO` - синий цвет для информации
+- `COLOR_OK` - зелёный цвет для успеха
+- `COLOR_ERR` - красный цвет для ошибок
+- `COLOR_WARN` - жёлтый цвет для предупреждений
+
+**Отключение цветов (для CI):**
+```bash
+COLOR_RESET= COLOR_INFO= COLOR_OK= COLOR_ERR= COLOR_WARN=
+```
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -0,0 +1,351 @@
+# 🐛 Решение проблем
+
+## Частые ошибки
+
+### 1. "missing separator. Stop."
+**Причина:** В Makefile используются пробелы вместо табов.
+
+**Решение:**
+```bash
+sed -i 's/^    /\t/' makefile
+```
+
+### 2. "docker: command not found"
+**Причина:** Docker не установлен или не в PATH.
+
+**Решение:**
+```bash
+# Установка Docker
+curl -fsSL https://get.docker.com -o get-docker.sh
+sh get-docker.sh
+
+# Проверка
+docker version
+```
+
+### 3. "unauthorized: authentication required"
+**Причина:** Не выполнена авторизация в registry.
+
+**Решение:**
+```bash
+make docker login REGISTRY=hub.cism-ms.ru
+# или
+docker login hub.cism-ms.ru
+```
+
+### 4. "No rule to make target 'commit'"
+**Причина:** Использование старых команд без префикса группы.
+
+**Решение:**
+```bash
+# Вместо: make commit
+# Используйте: make git commit
+```
+
+### 5. "Образ не найден"
+**Причина:** Указан неверный SRC_IMAGE или IMAGE не собран.
+
+**Решение:**
+```bash
+# Проверка существующих образов
+docker images
+
+# Сборка образа
+make docker build IMAGE=myapp TAG=latest
+```
+
+### 6. "Buildx: no builder instance"
+**Причина:** Buildx не инициализирован.
+
+**Решение:**
+```bash
+# Создание builder'а
+make docker create-builder
+
+# Использование builder'а
+make docker use-builder
+```
+
+## Отладка
+
+### Просмотр конфигурации
+```bash
+# Показать конфигурацию
+make docker print-config
+
+# Проверить образ
+make docker inspect
+
+# Просмотр логов
+make docker build 2>&1 | tee build.log
+
+# Проверка Docker daemon
+docker info
+
+# Проверка доступных образов
+docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
+```
+
+## Проблемы с памятью
+
+### Увеличение лимита памяти для Docker
+```bash
+# В /etc/docker/daemon.json
+{
+  "default-ulimits": {
+    "memlock": {
+      "Hard": -1,
+      "Name": "memlock",
+      "Soft": -1
+    }
+  }
+}
+```
+
+### Очистка неиспользуемых ресурсов
+```bash
+# Очистка неиспользуемых образов
+docker image prune -f
+
+# Очистка неиспользуемых контейнеров
+docker container prune -f
+
+# Полная очистка системы
+docker system prune -a -f
+```
+
+## Проблемы с сетью
+
+### Проверка сетевых настроек
+```bash
+# Проверка сетевых интерфейсов
+docker network ls
+docker network inspect bridge
+
+# Тестирование подключения
+make docker check RUN_CMD="ping -c 3 8.8.8.8"
+
+# Проверка DNS
+make docker check RUN_CMD="nslookup google.com"
+```
+
+### Настройка прокси
+```bash
+# Настройка прокси для Docker
+mkdir -p /etc/systemd/system/docker.service.d
+cat > /etc/systemd/system/docker.service.d/http-proxy.conf << EOF
+[Service]
+Environment="HTTP_PROXY=http://proxy.example.com:8080"
+Environment="HTTPS_PROXY=http://proxy.example.com:8080"
+Environment="NO_PROXY=localhost,127.0.0.1"
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl restart docker
+```
+
+## Проблемы с правами доступа
+
+### Исправление прав на файлы
+```bash
+# Исправление прав на Makefile
+chmod +x makefile
+chmod 644 dockerfile
+
+# Проверка прав пользователя
+make docker check RUN_CMD="id && whoami"
+
+# Добавление пользователя в группу docker
+sudo usermod -aG docker $USER
+newgrp docker
+```
+
+### Проблемы с SELinux (CentOS/RHEL)
+```bash
+# Временное отключение SELinux
+sudo setenforce 0
+
+# Постоянное отключение SELinux
+sudo sed -i 's/SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
+sudo reboot
+```
+
+## Проблемы с производительностью
+
+### Медленная сборка
+```bash
+# Сборка с подробным выводом
+make docker build IMAGE=myapp TAG=v1.0.0 QUIET=0
+
+# Анализ времени сборки
+time make docker build IMAGE=myapp TAG=v1.0.0
+
+# Сборка без кэша для диагностики
+make docker build IMAGE=myapp TAG=v1.0.0 NO_CACHE=1
+```
+
+### Большой размер образа
+```bash
+# Анализ размера образа
+docker history myapp:latest
+
+# Анализ слоев
+docker run --rm -it \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  wagoodman/dive:latest myapp:latest
+
+# Сжатие образа
+make docker save SRC_IMAGE=myapp:latest COMPRESS=1
+```
+
+## Проблемы с registry
+
+### Ошибки авторизации
+```bash
+# Очистка кэша авторизации
+docker logout
+docker login
+
+# Проверка конфигурации Docker
+cat ~/.docker/config.json
+
+# Удаление старых токенов
+rm -rf ~/.docker/config.json
+docker login
+```
+
+### Проблемы с SSL сертификатами
+```bash
+# Добавление недоверенного registry
+echo '{"insecure-registries":["registry.example.com:5000"]}' | sudo tee /etc/docker/daemon.json
+
+# Перезапуск Docker
+sudo systemctl restart docker
+```
+
+## Проблемы с Git
+
+### "Not a git repository"
+```bash
+# Инициализация Git репозитория
+git init
+git remote add origin <url>
+
+# Проверка статуса
+make git status
+```
+
+### "Git push failed"
+```bash
+# Проверка текущей ветки
+git branch
+
+# Проверка удаленного репозитория
+git remote -v
+
+# Принудительный push (осторожно!)
+git push --force-with-lease origin main
+```
+
+## Проблемы с архивами
+
+### Ошибка при загрузке архива
+```bash
+# Проверка целостности архива
+sha256sum -c images/myapp_v1.0.0.tar.gz.sha256
+
+# Проверка размера файла
+ls -lh images/myapp_v1.0.0.tar.gz
+
+# Пересоздание архива
+make docker save SRC_IMAGE=myapp:latest COMPRESS=1
+```
+
+### Проблемы с разбиением на части
+```bash
+# Объединение частей архива
+cat images/myapp_v1.0.0.tar.gz.part.* > images/myapp_v1.0.0.tar.gz
+
+# Проверка целостности
+sha256sum -c images/myapp_v1.0.0.tar.gz.sha256
+```
+
+## Диагностические команды
+
+### Проверка системы
+```bash
+# Информация о системе
+uname -a
+cat /etc/os-release
+
+# Информация о Docker
+docker version
+docker info
+
+# Информация о Make
+make --version
+
+# Информация о Git
+git --version
+```
+
+### Проверка ресурсов
+```bash
+# Использование диска
+df -h
+
+# Использование памяти
+free -h
+
+# Использование CPU
+top -n 1
+
+# Процессы Docker
+ps aux | grep docker
+```
+
+### Логи системы
+```bash
+# Логи Docker
+sudo journalctl -u docker.service
+
+# Логи системы
+sudo journalctl -f
+
+# Логи сборки
+tail -f logs/build_*.log
+```
+
+## Получение помощи
+
+### Сбор информации для отчета об ошибке
+```bash
+# Создание отчета об ошибке
+{
+  echo "=== System Info ==="
+  uname -a
+  cat /etc/os-release
+  
+  echo -e "\n=== Docker Info ==="
+  docker version
+  docker info
+  
+  echo -e "\n=== Make Info ==="
+  make --version
+  
+  echo -e "\n=== Git Info ==="
+  git --version
+  
+  echo -e "\n=== Project Config ==="
+  make docker print-config
+  
+  echo -e "\n=== Recent Logs ==="
+  tail -20 logs/build_*.log 2>/dev/null || echo "No logs found"
+} > bug_report.txt
+```
+
+### Полезные ресурсы
+- [Docker Documentation](https://docs.docker.com/)
+- [Make Documentation](https://www.gnu.org/software/make/manual/)
+- [Git Documentation](https://git-scm.com/doc)
+- [Stack Overflow](https://stackoverflow.com/questions/tagged/docker)