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

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