Как передать Docker-проект коллеге: проверка с чистого checkout

Коллега получил репозиторий, выполнил docker compose up и увидел страницу ошибки. На машине автора всё работает: нужный файл давно лежит рядом с проектом, база заполнена вручную, а переменные однажды были экспортированы в терминале. Контейнеризация зафиксировала часть окружения, но инструкция запуска всё ещё зависит от памяти одного человека.

Передачу проекта удобно проверять как первый пользовательский сценарий. У получателя есть Git, подходящий Docker и доступ к разрешённым внешним ресурсам. Всё остальное должно быть либо в репозитории, либо явно названо во входных условиях. Результат проверки — работающий запрос приложения и объяснимый способ повторить запуск, когда локальные контейнеры уже существуют.

Создайте независимую копию

Используйте новый checkout в отдельном каталоге, а не удаляйте файлы из рабочего проекта. Выберите новое имя Compose-проекта, например handoffcheck. Сначала изучите конфигурацию: external volumes, фиксированные container_name и bind mounts на абсолютные пути способны связать новую копию с прежней даже при другом имени проекта.

Команды ниже выполняются в новом checkout. Они читают состояние и конфигурацию; запуск сервисов будет отдельным действием после устранения найденных внешних привязок. Полный вывод config может содержать значения настроек, поэтому для отчёта достаточно перечня найденных проблем, без копирования секретов.

git status --short
docker compose -p handoffcheck config --quiet
docker compose -p handoffcheck config --services

Пустой git status помогает убедиться, что проверка началась с сохранённого состояния. config --quiet проверяет разбор конфигурации и подстановку переменных, но не подтверждает доступ к registry и работоспособность приложения. Если файл с обязательным параметром отсутствует, хорошо получить понятную ошибку уже здесь.

Разделите пример настроек и реальные значения

В репозитории нужен пример конфигурации: имена параметров, учебные адреса и объяснение обязательных значений. Реальные пароли и ключи пользователь получает отдельно. Для локальной лаборатории можно подготовить документированный способ генерации одноразовых значений. Важнее всего, чтобы получателю не пришлось угадывать, какая переменная действительно используется приложением.

Проверьте настройки из пустого терминального окружения. Экспортированная у автора DATABASE_URL способна незаметно перекрыть значение файла и скрыть ошибку инструкции. Если используются несколько Compose-файлов, в инструкции должна стоять полная команда с их порядком. Иначе получатель будет запускать другой набор портов, томов и сервисов.

Доведите пустую базу до первого действия

Новый том PostgreSQL начинается без прикладных таблиц. Опишите отдельную команду миграции и момент её выполнения. Если приложение само применяет миграции, объясните, как увидеть их успешное завершение и что произойдёт при повторном старте. Статус контейнера running не подтверждает наличие нужной схемы.

Для первого запроса могут понадобиться тестовый пользователь и справочники. Подготовьте небольшое заполнение с искусственными данными или шаг создания через API. Не переносите рабочий дамп только ради удобства демонстрации. Получатель должен понимать, какие данные учебные и как получить новое независимое окружение.

После запуска выполните содержательное действие: создайте тестовую запись, прочитайте её по выданному идентификатору и перезапустите приложение. Затем снова прочитайте запись. Эта последовательность одновременно проверяет схему, подключение и сохранение данных в предназначенном для этого томе. Открытая главная страница может не обращаться к базе вообще.

Опишите повторный старт и остановку

Первый запуск и обычное возвращение к проекту отличаются. Пересборка образа после изменения кода, запуск существующего окружения и очистка учебных данных должны быть отдельными понятными действиями. Команду, удаляющую volumes, нельзя прятать в ежедневный reset без объяснения потери данных.

Сделайте ещё один проход: остановите именно тестовый проект, запустите снова и повторите проверку записи. Если тест зависит от ручного исправления внутри контейнера, перенесите исправление в Dockerfile, конфигурацию или миграцию. Изменение внутри временного контейнера исчезнет при его пересоздании и снова сломает передачу.

Оставьте короткий раздел диагностики: команда просмотра статуса, журналы нужного сервиса, проверка доступного порта и ожидаемый первый ответ. Укажите требования к архитектуре процессора, если проект включает компоненты без нужного варианта образа. Эти сведения сокращают время между ошибкой получателя и полезным сообщением автору.

Проверяемость становится частью проекта

Хорошая инструкция описывает входные условия, запуск, первый результат и повторный цикл работы. Её можно выполнить по порядку на независимой копии. Когда такой сценарий существует, его проще перенести в автоматическую проверку, которая собирает проект и проверяет минимальное действие после изменения конфигурации.

Для независимой копии полезна проверка имени Compose-проекта. А скрытую зависимость от локального каталога помогает обнаружить разбор bind mount, закрывающего файлы образа.

Именно передаче приложения другому разработчику посвящён итоговый проект курса Docker и Docker Compose. Вы упакуете HTTP-сервис с PostgreSQL, настроите окружение и проверите восстановление данных. В программе есть Dockerfile-задачи с автоматической проверкой и локальные лабораторные. Откройте программу курса и соберите проект, который запускается по инструкции с чистого окружения.