Переписана документация
This commit is contained in:
Сергей Антропов
368
docs/makefile.md
Normal file
368
docs/makefile.md
Normal file
@@ -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=
|
||||
```
|
||||
Reference in New Issue
Block a user