Складання продукту: інтеграція артефактів, деплой, захист

Що робимо сьогодні

Модуль I · Хмарні сервіси й документи · тема 8, урок 2 з 2 · 120 хвилин

Після уроку ти вмієш

• звести чотири сторінки в один сайт: спільний style.css і дослівно однаковий блок меню;
• відправити зміни командою git push і за кілька секунд побачити їх на адресі сайту;
• перевірити кожну сторінку сайту й відрізнити 404 від 403;
• знайти за журналом, на якій ланці обірвалася публікація;
• показати роботу команди за п’ять хвилин, відкривши живий сайт.

Слова «деплой» і «вебхук» поки нічого не означають. Розберемо їх на кроці 5.

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

Урок складається з трьох частин, і кожна відповідає на своє питання.

Хід уроку

Що має бути на екрані наприкінці уроку

• адреса https://team3.<домен>/ відкривається з телефона сусіда, а не тільки з твого ноутбука;
• усі посилання в навігації ведуть на реальні сторінки — жодного «мертвого»;
• на сторінці команди видно, хто що зробив, і це збігається з історією комітів;
• чек-ліст готовності на цій сторінці показує 100%.

Чому чотири сторінки виглядають як чотири різні сайти

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

Читач не бачить чотирьох авторів. Він бачить один сайт, який «стрибає». На кожній сторінці інший шрифт. Меню з’їжджає вбік. Кнопка тут синя, а на сусідній сторінці зелена. Це виглядає недоробленим — навіть якщо кожна сторінка окремо зроблена добре.

Один файл стилів замість чотирьох

Найчастіша поламка інтеграції — у кожного своя копія стилів. Формально сайт працює. А потім ви міняєте колір заголовка — і правити доводиться в чотирьох файлах. На четвертому хтось забуде.

У цьому виводі — дві різні проблеми. Перша: media.html тягне власний файл стилів, його треба прибрати. Друга: dash/index.html лежить на рівень глибше. Для нього шлях style.css означає dash/style.css, а такого файлу немає. Правильно писати ../style.css. Сторінка відкриється, просто без оформлення.

Домовленість про імена — на п’ять хвилин, економить годину

На Windows файл Story.HTML відкриється за посиланням story.html. Помилки не буде. На сервері під Linux це два різні файли, і посилання дасть 404. Це найчастіша поламка, яку ми бачимо на цьому уроці з року в рік. Помилку не видно в автора — вона вилазить тільки після деплою.

• усі імена файлів і тек — малими латинськими літерами;
• роздільник — дефіс, не пробіл і не підкреслення: team-photo.svg;
• головна сторінка кожної теки зветься рівно index.html;
• жодної кирилиці в іменах — вона перетворюється на нечитабельний %D1%81%D1%82… у посиланні.

Структура спільного репозиторію

Репозиторій — не «тека, куди все кидають». Його структура і є домовленістю команди. Коли вона записана, усі знають, де що лежить, і посилання не ламаються.

Навіщо .gitignore

Це список того, що git ігнорує назавжди. Туди пишуть тимчасові файли редактора, теку з локальними відео, файли з паролями.

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

Що перетворює набір сторінок на продукт

Продукт — це коли людина, яка вас не знає, відкриває адресу і за 15 секунд розуміє, що це таке. Набір сторінок — це коли їй доводиться здогадуватися.

1. Головна, яка пояснює, що це

Типова головна сторінка командного сайту — це заголовок «Команда 3» і чотири посилання. Без автора поруч такий сайт не зрозуміти.

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

2. Навігація без «мертвих» посилань

Мертве посилання веде в нікуди. Це або <a href="gallery.html"> на сторінку, якої немає, або href="#", залишене «на потім». Читач читає це однаково: сайт зламаний.

Тут два різні діагнози. 404 — файлу немає: або його не закомічено, або ім’я інше. 403 у теці — файли в ній є, але серед них немає index.html. Показувати список файлів сервер не стане.

3. Сторінка команди з ролями

На team.html — по абзацу на людину. Що робив, який файл у репозиторії його, чого навчився.

«Допомагав з дизайном» не каже нічого. Пиши так: «зробив style.css і звів чотири сторінки до одного вигляду». І далі: «переверстав media.html, щоб на телефоні не було бічного скролу».

Той самий текст, тільки коротше, дублюється в CONTRIB.md. Звідти його читає чекер. Він звіряє імена з авторами комітів у git log. Учасника без жодного коміту видно одразу.

4. README.md — для того, хто прийде після вас

Сайт відкривається в браузері — і здається, що цього досить. Але наступного року репозиторій візьме інша команда. Або ви самі через півроку. README.md відповідає на питання, на які код не відповідає.

Деплой: що відбувається після git push

Ти дописав сторінку й зробив git push. Через кілька секунд її бачить будь-хто в інтернеті. Така публікація нової версії зветься деплоєм. Автоматичний деплой означає, що файли ніхто не копіює руками.

Ти лишаєш у магазині свій номер: «привезуть — набери мені». Дві програми домовляються так само: «станеться подія — постукай ось за цією адресою». Такий домовлений стук зветься вебхуком.

Gitea приймає твій push. Далі бере з налаштувань репозиторію адресу хука і шле на неї запит POST з описом події. За тією адресою чекає маленький скрипт. Він робить git pull у теку сайту.

Що всередині deploy.sh

Скрипт на сервері простіший, ніж здається. Головне в ньому — ключ --ff-only. Він забороняє серверу зливати гілки й розв’язувати конфлікти. Сервер або бере нову версію цілком, або не робить нічого. У другому випадку сайт лишається в робочому стані.

Симулятор деплою: знайди поламку за логом

Тисни «Зробити push» і читай журнал очима того, у кого не оновився сайт. У кожному прогоні може трапитися типова помилка. Назви її раніше за вчителя.

Демонстраційний режим: журнал згенеровано на цій сторінці. Формат рядків і коди відповідей — такі самі, як у справжньому ~/deploy.log і виводі curl.

Чому «в мене працює» не аргумент

Локально сторінка відкривається з файлової системи твоєї машини. В інтернеті — з теки на сервері під Linux, з того, що потрапило в git. Це три різні набори правил, і вони розходяться завжди в тих самих місцях.

Сторінку з теки сервера браузеру віддає окрема програма. Вона приймає запит, знаходить потрібний файл і надсилає його назад. Цю програму звуть nginx — на схемі нижче вона остання ланка.

Три різниці, через які ламається саме твоя сторінка

Звідси одне робоче правило на весь сайт: усі шляхи відносні. style.css, story/index.html, ../style.css — так, C:\…, file:///…, /home/oksana/… — ні. Відносний шлях однаково працює і на твоєму диску, і на сервері.

Чек-ліст готовності продукту

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

Сторінка media.html: як показати те, чого немає на сервері

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

Сторінка media.html — це текстовий супровід медіа. Її читають, коли команди немає поруч: наступного року, з телефона, з іншого міста. Вона має бути зрозумілою сама по собі.

Субтитри як текст сторінки

Файл .vtt уже містить усе потрібне: таймкод і репліку. Перенести його на сторінку — хвилин десять роботи. Зате текст трейлера стає видно в пошуку, і його можна прочитати без відео.

На сторінці це стає таблицею з двох колонок: час і репліка. Або списком <dl>. Головне — щоб це був текст, а не картинка. Текст знайде пошук. А ще його прочитає вголос програма для незрячих — її звуть скрінрідером. І цитату з тексту можна скопіювати.

Захист: п’ять хвилин, щоб вас зрозуміли

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

Що показувати з екрана, а що з сайту

Про «що не вийшло» — чесно і конкретно

Слабка відповідь: «нам не вистачило часу». Сильна звучить так: «Фільтр галереї працює тільки мишею. З клавіатури він не вмикається. Ми помітили це вчора, коли пройшли сторінку клавішею Tab. Переписати не встигли: треба обробляти keydown».

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

Практика: зібрати і опублікувати

Кроки 1—4 робить уся команда разом за одним екраном, далі — кожен у своїй гілці. Галочки зберігаються, сторінку можна закрити.

Автоперевірка

Чекер відкриває ваш сайт так само, як стороння людина, і читає репозиторій через API Gitea. Він не знає, хто скільки старався, — він бачить коди відповідей і історію комітів. Спроби не обмежені.

Демонстраційний режим: результат згенеровано для показу. На сервері ця кнопка викликає POST /api/check, який запускає check 15 для репозиторію і сайту команди.

Що вчитель дивиться очно

• сайт команди відкривається з телефона вчителя, а не з ноутбука, де він «щойно працював»;
• кожен учасник називає, що саме зробив — і це збігається з CONTRIB.md та git log;
• на екрані команди йде комікс із локальними зображеннями і трейлер зі звуком;
• учасник відкриває media.html і показує, де там субтитри і посилання на prompts.json;
• будь-який учасник пояснює своїми словами, що робить інтерактивний елемент і хто його писав;
• команда називає одну річ, яка не вийшла, і причину.

Шкала виконання

Це те, що бачить учитель, коли виставляє оцінку.

П’ять речень, які варто запам’ятати

• чотири сторінки стають сайтом тоді, коли в них один style.css і дослівно однаковий <nav>;
• продукт — це коли незнайома людина за 15 секунд розуміє, що це і хто зробив;
• деплой автоматичний саме для того, щоб опубліковане завжди дорівнювало тому, що в main;
• «локально працює» ламається на трьох речах: регістр імен, абсолютні шляхи і файли, які не додано в git;
• на захисті показують продукт, а не код, і чесно називають те, що не вийшло.

Де найчастіше помиляються

• чотири копії стилів у чотирьох сторінках — правки роблять чотири рази;
• Comic.html у репозиторії і comic.html у посиланні — локально працює, на сервері 404;
• картинки не додано в git: сторінка є, зображень немає;
• тека розділу без index.html — сервер віддає 403;
• заголовок вкладки лишився Document на трьох сторінках із чотирьох;
• у CONTRIB.md є людина, у якої в git log нуль комітів;
• останній push зроблено за хвилину до захисту — і ніхто не встиг побачити, що деплой упав.

Домашнє завдання

Усунути зауваження після захисту й довести check 15 до зеленого. Окремо: дописати в README.md розділ «Що ми зробили б інакше» — 3—5 речень від команди, з конкретикою.

«Краще розподілили б час» — це ні про що. Пиши конкретно: «Домовилися б про імена файлів на першому уроці теми. Три людини назвали головні сторінки розділів по-різному. Ми втратили близько години, поки лагодили посилання».

Звідки взяті правила й формулювання

Тексти помилок git, коди відповідей HTTP і вимоги доступності на цій сторінці — зі стандартів і офіційної документації. Перевіряти дозволено й корисно.

• Gitea Docs — Webhooks: як налаштувати хук, що приходить у тілі події push, де дивитися Recent Deliveries. docs.gitea.com/usage/webhooks
• Документація git-pull — режим --ff-only і повідомлення Your local changes would be overwritten by merge. git-scm.com/docs/git-pull
• Документація git-status і gitignore — розділ Untracked files, правила ігнорування. git-scm.com/docs/gitignore
• MDN — HTTP-коди відповідей: 200, 403, 404 і що кожен із них означає для сторінки й для теки. developer.mozilla.org/HTTP/Status
• nginx — директива index і autoindex: чому тека без index.html віддає 403. nginx.org/ngx_http_index_module
• MDN — відносні й абсолютні URL: чим style.css відрізняється від /style.css і від file:///…. developer.mozilla.org/What_is_a_URL
• WCAG 2.2, критерій 1.1.1 Non-text Content — вимога текстової альтернативи (alt) до зображень. w3.org/WAI/WCAG22/non-text-content
• WCAG 2.2, критерій 2.4.2 Page Titled — заголовок сторінки має описувати її тему; звідси заборона на Document. w3.org/WAI/WCAG22/page-titled
• WCAG 2.2, критерій 1.4.10 Reflow — сторінка має читатися без горизонтального скролу на вузькому екрані. w3.org/WAI/WCAG22/reflow
• MDN — формат WebVTT: структура файлу субтитрів, таймкоди. developer.mozilla.org/WebVTT_API
• OWASP — Secrets Management Cheat Sheet: чому секрет у репозиторії вважається скомпрометованим і його треба відкликати, а не видаляти. cheatsheetseries.owasp.org/Secrets_Management
• GitHub Docs — Removing sensitive data from a repository: секрет лишається в історії комітів навіть після видалення файлу. docs.github.com/removing-sensitive-data
• Make a README — мінімальний набір розділів README і навіщо кожен. makeareadme.com
• curl — довідка: ключі -o, -s, -w "%{http_code}", -I. curl.se/docs/manpage.html
• Microsoft Learn — Invoke-WebRequest: чому в Windows PowerShell curl означає не те, що в Git Bash. learn.microsoft.com/invoke-webrequest

Повний список із поясненнями, що звідки взято, — у файлі urok-15-джерела.md поруч із цією сторінкою.