========================================================= UNIVERSAL MAKEFILE FOR DOCKER AND GIT ========================================================= Автор: Sergey Antropov Версия: 2.0 Описание: Универсальный Makefile для управления Docker-образами, их сборкой, сохранением, загрузкой, публикацией, а также интеграцией с Git. ========================================================= РАЗДЕЛ 1. ОБЩЕЕ ОПИСАНИЕ ========================================================= Makefile предназначен для автоматизации типовых задач DevOps: - сборка Docker-образов (включая Buildx) - сохранение и загрузка архивов образов (save/load) - оффлайн публикация (ретег и push) - логирование всех операций - Git-команды (commit, push, pull, sync) - быстрая проверка сборки через RUN_CMD Все сценарии универсальны, не требуют внешних зависимостей кроме установленного Docker и Git. ========================================================= РАЗДЕЛ 2. ОСНОВНЫЕ КОМАНДЫ ========================================================= Формат вызова: make <группа> <действие> [переменные] --------------------------------------------------------- ГРУППА: docker --------------------------------------------------------- make docker build Собрать Docker-образ. Примеры: make docker build IMAGE=myapp TAG=latest make docker build NO_CACHE=1 make docker build USE_BUILDX=1 PLATFORMS="linux/amd64,linux/arm64" make docker check Проверить образ, запустив RUN_CMD внутри контейнера. Пример: make docker check RUN_CMD="java -version" make docker push Собрать, проверить и отправить образ в registry. Пример: make docker push IMAGE=myapp TAG=v1.0 make docker login Авторизация в Docker Registry. Пример: make docker login REGISTRY=hub.cism-ms.ru make docker save Сохранить локальный образ в архив (tar или tar.gz). Поддерживает разбиение на части. Пример: make docker save SRC_IMAGE=myapp:latest COMPRESS=1 SPLIT_SIZE=2G make docker load Загрузить архив, ретегнуть и (опционально) запушить. Пример: make docker load ARCHIVE=images/myapp.tar LOGIN=1 PUSH_OFFLINE=1 make docker retag Перетегировать образ. Пример: make docker retag NEW_TAG=v2.0 make docker inspect Просмотреть метаданные Docker-образа. make docker clean Очистить временные каталоги logs/ и .offline/. make docker print-config Показать текущие значения всех переменных. make docker create-builder Создать buildx builder для мультиплатформенной сборки. make docker use-builder Активировать ранее созданный builder. --------------------------------------------------------- ГРУППА: git --------------------------------------------------------- make git status Показать текущее состояние репозитория. make git pull Получить последние изменения из origin. make git commit Добавить и закоммитить изменения. Если GIT_MSG не задана — запросит ввод вручную. make git push Создать коммит (если есть изменения) и отправить в origin. make git sync Выполнить pull, commit и push последовательно. ========================================================= РАЗДЕЛ 3. ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ (ПОДРОБНО) ========================================================= Любая переменная может быть переопределена при вызове make: make docker build IMAGE=myapp TAG=v1.0 NO_CACHE=1 --------------------------------------------------------- DOCKER-ПЕРЕМЕННЫЕ --------------------------------------------------------- REGISTRY Адрес Docker Registry без протокола. Пример: hub.cism-ms.ru/library IMAGE Имя Docker-образа (обязательное поле при сборке). TAG Тег образа. По умолчанию: latest. CONTEXT Папка контекста сборки. По умолчанию — текущая директория. DOCKERFILE Имя Dockerfile, используемого при сборке. USE_BUILDX 1 — использовать Docker Buildx (для мультиплатформенной сборки). 0 — обычный docker build. PLATFORMS Целевые платформы для buildx. Пример: linux/amd64,linux/arm64. PUSH 1 — выполнить docker push после buildx. 0 — не выполнять. LOAD 1 — загрузить образ в локальный docker после сборки. 0 — не загружать (актуально для CI/CD). NO_CACHE 1 — сборка без кэша. 0 — использовать кэш. PULL 1 — принудительно обновить базовые образы. 0 — использовать локальные. QUIET 1 — минимальный вывод в консоль. 0 — стандартный. BUILD_ARGS Дополнительные аргументы docker build. Пример: BUILD_ARGS="--build-arg VERSION=1.0 --build-arg DEBUG=1" ARG_FILE Путь к файлу KEY=VALUE. Все пары превращаются в --build-arg KEY=VALUE. RUN_CMD Команда для проверки контейнера после сборки. По умолчанию: lsb_release -a BUILDER Имя buildx builder'а (по умолчанию universal-builder). LOG_DIR Каталог для логов сборок (по умолчанию logs/). LOG_FILE Файл лога, формируется автоматически с датой и временем. --------------------------------------------------------- ОФФЛАЙН-ПЕРЕМЕННЫЕ (SAVE / LOAD) --------------------------------------------------------- ARCHIVE Путь к архиву образа (tar или gz). LOGIN 1 — выполнить docker login перед push. 0 — пропустить. PUSH_OFFLINE 1 — выполнить docker push после загрузки архива. 0 — только загрузить. KEEP_SRC_TAG 1 — использовать тег из архива. 0 — использовать TAG из Makefile. IMAGES_DIR Каталог для сохранения архивов Docker-образов (по умолчанию images/). OFFLINE_DIR Временная служебная папка (.offline). SRC_IMAGE Имя исходного образа для сохранения. COMPRESS 1 — сжать gzip. 0 — оставить tar. SPLIT_SIZE Размер чанка для split (например 2G). LAST_SAVE Путь к последнему сохранённому архиву. --------------------------------------------------------- GIT-ПЕРЕМЕННЫЕ --------------------------------------------------------- GIT_REMOTE Имя удалённого репозитория (по умолчанию origin). GIT_BRANCH Текущая ветка (определяется автоматически). GIT_MSG Сообщение коммита. Если не задано — будет запрошено вручную. --------------------------------------------------------- ПРОЧИЕ --------------------------------------------------------- FULL_IMAGE Полное имя образа REGISTRY/IMAGE:TAG (формируется автоматически). Цвета (COLOR_INFO, COLOR_OK, COLOR_ERR, COLOR_WARN) ANSI-коды для форматирования вывода. Можно обнулить, чтобы отключить цвет в CI. ========================================================= РАЗДЕЛ 4. ПРИМЕРЫ ========================================================= 1. Сборка без кэша: make docker build NO_CACHE=1 2. Сборка и пуш мультиплатформенного образа: make docker build USE_BUILDX=1 PUSH=1 LOAD=0 PLATFORMS="linux/amd64,linux/arm64" 3. Проверка образа: make docker check RUN_CMD="java -version" 4. Сохранение и сжатие: make docker save SRC_IMAGE=myapp:latest COMPRESS=1 5. Загрузка и пуш: make docker load ARCHIVE=images/myapp.tar LOGIN=1 PUSH_OFFLINE=1 6. Коммит и пуш в git: make git push GIT_MSG="Обновлены зависимости" 7. Быстрое обновление ветки: make git sync ========================================================= РАЗДЕЛ 5. ВОЗМОЖНЫЕ ПРОБЛЕМЫ И РЕШЕНИЯ ========================================================= --------------------------------------------------------- 1. Ошибка: "missing separator. Stop." --------------------------------------------------------- Причина: В Makefile должны быть табы, а не пробелы. Решение: Преобразовать пробелы в табы: sed -i 's/^ /\t/' Makefile --------------------------------------------------------- 2. Ошибка: "unknown instruction: yum (did you mean RUN?)" --------------------------------------------------------- Причина: В Dockerfile после инструкции `RUN <<EOF` забыта команда RUN. Решение: Убедись, что после каждой строки в Dockerfile используется RUN или символ обратной косой черты `\` при переносе строк. --------------------------------------------------------- 3. Ошибка: "No rule to make target 'commit'" --------------------------------------------------------- Причина: Старые вызовы команд без указания группы git (например, `make commit`). Решение: Используй новую структуру: make git commit или make git push --------------------------------------------------------- 4. Ошибка: "Not a git repository" --------------------------------------------------------- Причина: Текущая папка не является Git-репозиторием. Решение: Инициализируй git: git init git remote add origin <url> --------------------------------------------------------- 5. Ошибка: "docker: command not found" --------------------------------------------------------- Причина: Docker не установлен или не добавлен в PATH. Решение: Установи Docker и проверь: docker version --------------------------------------------------------- 6. Ошибка при push: "unauthorized: authentication required" --------------------------------------------------------- Причина: Не выполнен docker login в registry. Решение: Выполни: make docker login REGISTRY=hub.cism-ms.ru или авторизуйся вручную: docker login hub.cism-ms.ru --------------------------------------------------------- 7. Ошибка: "Образ не найден" --------------------------------------------------------- Причина: Указан неверный SRC_IMAGE или IMAGE не собран. Решение: Убедись, что образ существует: docker images Или собери его: make docker build --------------------------------------------------------- 8. Ошибка checksum при загрузке архива --------------------------------------------------------- Причина: Повреждён файл tar.gz. Решение: Проверить хеш-сумму: sha256sum images/*.sha256 Пересобрать архив: make docker save SRC_IMAGE=myapp:latest COMPRESS=1 --------------------------------------------------------- 9. Ошибка "Git push failed" --------------------------------------------------------- Причина: Нет прав на запись в репозиторий или неверная ветка. Решение: Проверь текущую ветку: git branch Выполни повторно push: make git push GIT_MSG="Обновление" --------------------------------------------------------- 10. Ошибка Buildx: "no builder instance" --------------------------------------------------------- Причина: Buildx не инициализирован. Решение: Создай builder: make docker create-builder Затем используй: make docker use-builder ========================================================= РАЗДЕЛ 6. СОВЕТЫ ПО ИСПОЛЬЗОВАНИЮ ========================================================= - Всегда задавай REGISTRY и IMAGE при сборке. - Для CI/CD добавь NO_CACHE=1 и QUIET=1. - Для оффлайн-деплоя используй SAVE/LOAD. - Git-команды можно вызывать без аргументов — Makefile запросит сообщение сам. - Если часто работаешь с конкретными параметрами — создай файл `.env` или `Makefile.local`. ========================================================= ЛИЦЕНЗИЯ ========================================================= MIT License Свободно для использования в любых проектах. =========================================================