Проєкт запускається лише в автора? Як зробити старт для новачка відтворюваним

Коли одна команда перетворюється на годину помилок

Команда каже новому розробнику: клонуй репозиторій, виконай одну команду — і все запрацює. За годину людина вже надсилає третій знімок екрана з помилкою. Спочатку не підходить версія середовища виконання, потім бракує змінної середовища, а далі з’ясовується, що один сервіс існує лише на ноутбуці автора.

У такій ситуації легко вирішити, що новачок недостатньо уважний. Корисніше поставити інше запитання: чи може команда повторити робоче середовище без знань, які зберігаються лише в чиїйсь пам’яті?

Контейнеризацію часто пропонують як швидку відповідь. Але наявність Dockerfile або іншого опису контейнера ще не доводить, що запуск став простішим. Це треба перевірити до і після змін за однаковими критеріями.

Розробник Mohammad-Ali A’râbi наводить у Docker Blog конкретний приклад: у 2015 році він цілий тиждень не міг запустити Django-проєкт через конфлікти залежностей. Через кілька років, уже в іншій компанії, він упровадив Docker і автоматичні перевірки коду. Це пояснює, чому розробники звертаються до контейнеризації, але не означає, що вона сама усуває всі проблеми із запуском. Результат усе одно треба перевірити на власному проєкті.

Прохід 1: зафіксуйте реальний стан

Почніть із тесту на чистому середовищі. Використайте нову віртуальну машину, окремий ноутбук або тимчасове середовище без старих кешів і локальних налаштувань автора.

Зафіксуйте початкові умови:

• яку операційну систему та архітектуру ви використовуєте;
• що встановлено до клонування репозиторію;
• яку гілку й версію коду перевіряєте;
• коли запускаєте таймер;
• що саме вважаєте успіхом.

Успіх має бути видимим. Наприклад, застосунок відповідає на перевірку готовності, потрібна міграція бази завершилася, а базовий набір тестів пройшов. Формулювання «процес не впав» недостатньо: програма може працювати, але не мати з’єднання з базою чи чергою.

Виконуйте README буквально. Для кожної зупинки запишіть команду, текст помилки, причину, спосіб виправлення та витрачений час. Не виправляйте документацію під час проходу: спочатку потрібна чесна картина. Саме цей журнал покаже приховані версії, файли, порти та ручні кроки.

Що контейнер може зафіксувати, а що залишиться зовні

Добре описаний контейнерний образ може зафіксувати середовище виконання, системні пакети, програмні залежності та команду запуску. Це зменшує вплив випадкових відмінностей між ноутбуками й допомагає відтворити однакову основу в CI.

Проте контейнер не містить увесь світ проєкту. За його межами залишаються архітектура машини, мережевий доступ, зовнішня база даних, дозволи на файли, секрети та підтримувані версії пов’язаних сервісів. Якщо застосунок мовчки очікує локальний файл або ручне створення черги, проблема просто переїде всередину нового сценарію запуску.

Так само небезпечно покладатися на плаваючі теги образів. Якщо команда щоразу отримує різний вміст під тією самою назвою, відтворюване середовище зникає. Для важливих складників потрібні явно вибрані версії та зрозуміла процедура оновлення.

Прохід 2: повторіть тест за тими самими правилами

Після змін знову почніть із чистого середовища. Не використовуйте образи, кеші або конфігурацію з першого проходу.

Бажаний шлях короткий: установити заявлені передумови, клонувати репозиторій, створити локальну конфігурацію з безпечного шаблону й виконати одну документовану команду. Окрема команда перевірки має показати, чи готові застосунок і залежні сервіси.

CI повинен використовувати ті самі основні кроки складання й тестування. Це не означає, що локальний ноутбук і CI мусять бути повністю однаковими. Але вони не повинні збирати програму різними способами або встановлювати різні набори залежностей.

Порівняйте два проходи за часом до першого успіху, кількістю зупинок, ручних дій і незадокументованих вимог. Окремо перевірте, чи інша людина може повторити результат без усних підказок.

Як читати типові результати

• Локально працює, у CI — ні. Шукайте локальний кеш, підключений файл, іншу команду або залежність від сервісу на машині розробника.
• CI працює, чистий ноутбук — ні. Імовірно, важлива підготовка описана лише в конфігурації CI, а README її не повторює.
• Повторне складання раптово ламається. Перевірте плаваючі версії базових образів і залежностей.
• Для запуску треба вставити ключ у файл образу. Не робіть цього. Секрет має надходити під час виконання через дозволений командою механізм і не потрапляти до історії складання.
• Контейнеру потрібні надмірні права. Перевірте файлові дозволи та запускайте процес без зайвих привілеїв.
• Інструкція містить багато ручних виправлень. Автоматизуйте повторювані кроки або зробіть їх явними перевірками з чіткими повідомленнями про помилку.

Поганий шаблон — використовувати контейнер як архів ноутбука автора. Інший поганий шаблон — приховати довгий ланцюг дій за однією командою без перевірки помилок. Одна команда корисна лише тоді, коли її результат можна зрозуміти й повторити.

Залиште коротку інструкцію

Підсумкова інструкція може вміститися на одній сторінці. Додайте заявлені передумови, одну команду запуску, ознаку готовності, назви потрібних змінних середовища, типові помилки та команди зупинки й очищення.

Також зазначте, як оновлювати залежності, хто відповідає за документ і коли команда повторить тест на чистому середовищі. Перевірку варто запускати після зміни середовища виконання, базового образу або важливої зовнішньої служби.

Контейнеризація допомогла, якщо другий прохід став швидшим, передбачуванішим і ближчим до CI. Якщо кількість прихованих кроків не зменшилася, команда не розв’язала проблему — лише перемістила її. Мета не в наявності контейнера, а в тому, щоб наступна людина могла отримати той самий результат без здогадок.

Джерела

• Docker Blog — From the Captain’s Chair: Mohammad-Ali A’râbi: https://www.docker.com/blog/from-the-captains-chair-mohammad-ali-arabi/