Dockerfile/docs/makefile.md

# ⚙️ Makefile

## Основные команды

### Docker команды

| Команда | Описание | Пример |
|---------|----------|--------|
| `make docker build` | Собрать Docker-образ (двойные теги) | `make docker build IMAGE=myapp TAG1=latest TAG2=v1.0` |
| `make docker check` | Проверить образ | `make docker check RUN_CMD="java -version"` |
| `make docker push` | Собрать + проверить + отправить (оба тега) | `make docker push IMAGE=myapp TAG1=latest TAG2=v1.0` |
| `make docker rebuild` | Пересобрать без кэша (оба тега) | `make docker rebuild IMAGE=myapp TAG1=latest TAG2=v1.0` |
| `make docker pull` | Скачать/обновить образы по тегам | `make docker pull IMAGE=myapp TAG1=latest TAG2=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
```

#### TAG1 / TAG2
**Описание:** Основной и дополнительный тег образа (двойное тегирование)  
**По умолчанию:** `TAG1=latest`, `TAG2=v.0.0.1`  
**Примеры:**
```bash
TAG1=latest TAG2=v1.0.0
TAG1=stable TAG2=v1.0.1
TAG1=dev    # без второго тега
```

#### 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 / FULL_IMAGE_1 / FULL_IMAGE_2
**Описание:** Полные имена образов  
**Формируется автоматически:**
- `FULL_IMAGE` = `$(REGISTRY)/$(IMAGE):$(TAG1)`
- `FULL_IMAGE_1` = `$(REGISTRY)/$(IMAGE):$(TAG1)`
- `FULL_IMAGE_2` = `$(REGISTRY)/$(IMAGE):$(TAG2)`
**Примеры:**
```bash
FULL_IMAGE_1=hub.cism-ms.ru/library/myapp:latest
FULL_IMAGE_2=hub.cism-ms.ru/library/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=
```