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

2025-10-29 14:47:35 +03:00
parent e466f14d49
commit e4e23b88ca
10 changed files with 2528 additions and 403 deletions
--- 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
+```