ddadmin
4ad904efd0
Deploy MkDocs to VPS / deploy (push) Successful in 13s
- Зачем: - runbook требовал незафиксированного контекста для первого деплоя и восстановления сайта на чистой VPS. - Что: - добавлены prerequisites, установка пакетов, первый workflow, UFW и проверенный атомарный откат. - спецификация и PRD обновлены по факту завершённого переноса на VPS. - локальные команды Snap uv заменены на persistent Python venv. - Проверка: - mkdocs build --strict выполнен через persistent venv пользователя gitea-runner. - последовательность rollback проверена на временном дереве releases и symlink.
175 lines
14 KiB
Markdown
175 lines
14 KiB
Markdown
# PRD: Сайт для de-roadmap
|
||
|
||
> Проектный документ. Техническая архитектура — в отдельном ADR.
|
||
|
||
---
|
||
|
||
## 1. Контекст и мотивация
|
||
|
||
### Текущее состояние
|
||
|
||
Роадмап по Data Engineering живёт как Git-репозиторий. Основной origin
|
||
размещён в собственной Gitea
|
||
([ddmitry/de-roadmap](https://git.dementev.space/ddmitry/de-roadmap)), а
|
||
GitHub Pages сохраняется как резерв после восстановления доступа к GitHub:
|
||
|
||
- Основной контент — монолитный `README.md` (~700 строк) с полным учебным планом.
|
||
- Дополнительные материалы — в подпапках (`dwh-modeling/`, `postgres-bookings/`): теория DWH-моделирования, SCD, Data Vault, домашние задания, скрипты.
|
||
- 109 коммитов, контент активно развивается.
|
||
- Основной поток менти приходит через маркетплейс ОМ (Осознанная Меркантильность) — платформу менторства с системой отзывов, ранжированием менторов и модерацией. Участие платное (абонентская плата + аукцион за позицию в выдаче).
|
||
- Роадмап изначально создавался для себя — как конспект подходов к обучению. Со временем стал использоваться и для менти (удобная структура прохождения), и на ознакомительных созвонах с лидами из ОМ (демонстрация программы и подхода к обучению).
|
||
- Отдельного маркетингового продвижения роадмапа не было, органических приходов «по ссылке из интернета» — ноль. Сайта ментора тоже пока нет — приходить некуда.
|
||
|
||
### Проблема
|
||
|
||
GitHub README — рабочий, но не презентабельный формат:
|
||
|
||
- Нет удобной навигации по длинному документу (только ручной скролл или оглавление-ссылки).
|
||
- Выглядит как «техническая документация», а не как продукт ментора.
|
||
- GitHub README плохо индексируется поисковыми системами — роадмап в таком виде даже потенциально не может привлекать органический трафик и «продавать сам себя».
|
||
- Неудобно давать ссылку потенциальному менти — GitHub-интерфейс отвлекает (issues, commits, файловое дерево).
|
||
- Нет мобильной адаптации контента (GitHub на телефоне — страдание).
|
||
|
||
### Чего НЕ решаем этим проектом
|
||
|
||
- **Лидогенерацию и воронку продаж.** Основной поток тёплых лидов идёт через маркетплейс ОМ, и конкурировать с ним по объёму нереалистично — даже топовые менторы не добирают сравнимое количество лидов из других источников. В перспективе сайт может стать элементом маркетинговой воронки (Habr → сайт → менторство), но это отдалённая цель, не влияющая на текущие решения. Сейчас сайт — витрина экспертизы, а не маркетинговый инструмент.
|
||
- **Масштабирование менторского бизнеса.** Сейчас приоритет — выпустить текущих менти, а не набрать новых.
|
||
- **Создание LMS / интерактивного курса.** Формат остаётся «структурированный текст + ссылки», без трекинга прогресса и автопроверок.
|
||
|
||
---
|
||
|
||
## 2. Цели
|
||
|
||
| # | Цель | Метрика успеха |
|
||
|---|------|----------------|
|
||
| 1 | Удобная читаемая версия роадмапа | Сайт с навигацией, поиском, мобильной версией |
|
||
| 2 | Репозиторий остаётся полностью рабочим без сайта | Все `.md` файлы читаемы на GitHub, ссылки между ними работают |
|
||
| 3 | Минимальные накладные расходы на поддержку | Обновил `.md` → запушил → сайт обновился автоматически |
|
||
| 4 | Презентабельный вид для демонстрации на созвонах | Ссылка, которую удобно показать лиду из ОМ при обсуждении программы |
|
||
|
||
---
|
||
|
||
## 3. Целевая аудитория
|
||
|
||
**Основная:** менти (текущие и потенциальные) — джуны и переходящие в DE из смежных областей. Приходят по рекомендации из ОМ или по прямой ссылке от ментора. Им нужно быстро оценить объём программы и найти нужный раздел.
|
||
|
||
**Вторичная:** коллеги-инженеры, которые наткнулись на репозиторий через GitHub/поиск. Для них важна полнота контента и техническая достоверность, а не «продающие» элементы.
|
||
|
||
---
|
||
|
||
## 4. Требования
|
||
|
||
### 4.1. Обязательные (MVP)
|
||
|
||
**Контент и структура:**
|
||
|
||
- [x] Главная страница сайта = полный текст текущего `README.md` (одна длинная страница, не разбиваем).
|
||
- [x] Подстраницы из существующих `.md` файлов (`dwh-modeling/README.md`, `SCD.md`, `DataVault.md`, домашки).
|
||
- [x] Автоматическое оглавление (Table of Contents) по заголовкам H2/H3 на главной странице.
|
||
- [x] Внутренние ссылки работают и на GitHub, и на сайте (dual-compatible links).
|
||
|
||
**Навигация:**
|
||
|
||
- [x] Боковая панель с разделами сайта (основной README + подразделы).
|
||
- [x] Оглавление текущей страницы (правый sidebar / TOC).
|
||
- [x] Полнотекстовый поиск по сайту.
|
||
|
||
**Деплой:**
|
||
|
||
- [x] Автоматическая сборка и публикация при пуше в `main`.
|
||
- [x] Публикация без дополнительных расходов: собственная VPS как основной
|
||
контур, GitHub Pages как резерв.
|
||
|
||
**Совместимость с репо:**
|
||
|
||
- [x] Все `.md` файлы остаются читаемыми на GitHub «как есть».
|
||
- [x] `README.md` в корне репо продолжает рендериться на главной странице репозитория.
|
||
- [x] Добавление сайта не ломает существующую структуру — если удалить конфиг сайта, репо работает как раньше.
|
||
|
||
### 4.2. Желательные (Спринт 2+)
|
||
|
||
- [x] Кастомный домен: `de.dementev.space` (подключён 2026-03-27, переведён на
|
||
VPS 2026-08-05).
|
||
- [x] Тёмная тема (переключатель light/dark).
|
||
- [x] Сворачиваемые блоки (`<details>`) — точечно, для подсказок/решений в домашках (2026-03-29).
|
||
- [x] Кнопка «Написать в Telegram» — floating-кнопка + иконки в футере (2026-03-29).
|
||
- [ ] Иконки/бейджи для статуса разделов (пройден / в процессе / не начат) — пока декоративные, без бэкенда.
|
||
- [x] Яндекс.Метрика — счётчик 108294923, вебвизор, карта кликов (2026-03-29).
|
||
|
||
### 4.3. Явно НЕ делаем
|
||
|
||
- Разбивку основного README на отдельные страницы.
|
||
- Интерактивный трекинг прогресса менти.
|
||
- Систему авторизации / личный кабинет.
|
||
- Блог или раздел новостей (для этого есть Telegram-канал).
|
||
- SEO-оптимизацию и маркетинговые landing pages.
|
||
|
||
---
|
||
|
||
## 5. Ограничения
|
||
|
||
- **Бюджет: 0 ₽** (кроме домена, если решим подключить кастомный — `dementev.space` уже есть).
|
||
- **Время на поддержку: минимальное.** Рабочий процесс = «редактирую `.md` → push → сайт обновляется». Не должно быть отдельного шага сборки, ручного деплоя или npm-зависимостей, требующих обновления.
|
||
- **Стек автора: Python-first.** Решение на Python-тулинге предпочтительнее, чем на Node.js/Ruby (проще отлаживать при необходимости).
|
||
- **Один мейнтейнер.** Сайт поддерживает один человек — сложность решения должна быть соответствующей.
|
||
|
||
---
|
||
|
||
## 6. Итерации
|
||
|
||
### Спринт 1 — MVP: «Сайт, который просто работает» ✅ (2026-03-27)
|
||
|
||
**Scope:**
|
||
|
||
- Конфигурация генератора статического сайта.
|
||
- CI/CD pipeline (GitHub Actions → GitHub Pages).
|
||
- Главная страница = README.
|
||
- Подстраницы из `dwh-modeling/`.
|
||
- Фикс внутренних ссылок для dual compatibility.
|
||
- Адаптация Markdown для Python-Markdown (пустые строки перед списками, 4-пробельные отступы, заголовки `#`→`##`).
|
||
|
||
**Definition of Done:**
|
||
|
||
- ~~Сайт доступен по URL `https://dementev-dev.github.io/de-roadmap/`.~~ → `https://de.dementev.space/`
|
||
- Все ссылки внутри README работают и на сайте, и на GitHub.
|
||
- При пуше в `main` сайт автоматически пересобирается за < 2 минут (факт: ~34 сек).
|
||
- Контент на GitHub выглядит ровно так же, как до добавления сайта.
|
||
|
||
### Спринт 2 — «Удобство и навигация» (в процессе)
|
||
|
||
**Scope:**
|
||
|
||
- ~~Кастомный домен.~~ ✅ `de.dementev.space` (2026-03-27)
|
||
- ~~Тёмная тема.~~ ✅ из коробки Material (2026-03-27)
|
||
- ~~Сворачиваемые блоки.~~ ✅ `<details>` точечно в домашках (2026-03-29)
|
||
- ~~Кнопка «Написать ментору» (Telegram).~~ ✅ floating + футер (2026-03-29)
|
||
- ~~Базовая аналитика.~~ ✅ Яндекс.Метрика (2026-03-29)
|
||
|
||
### Спринт 3 — «Контент и визуал» (по необходимости)
|
||
|
||
**Scope:**
|
||
|
||
- Визуальная карта роадмапа (интерактивная диаграмма прохождения).
|
||
- Страница «О менторе» / «Отзывы выпускников» (когда будут выпускники).
|
||
- Расширение контента: новые разделы роадмапа → автоматически появляются на сайте.
|
||
|
||
---
|
||
|
||
## 7. Риски
|
||
|
||
| Риск | Вероятность | Влияние | Митигация |
|
||
|------|-------------|---------|-----------|
|
||
| Ссылки ломаются при конвертации (GitHub vs сайт) | Средняя | Высокое | Стратегия dual-compatible links в ADR; автотест ссылок в CI |
|
||
| Кириллические якоря рендерятся по-разному | Средняя | Среднее | Тестирование конкретного генератора; при необходимости — латинские id |
|
||
| Генератор сайта перестаёт поддерживаться | Низкая | Среднее | Контент в plain Markdown — миграция на другой генератор за день |
|
||
| Накладные расходы на поддержку растут | Низкая | Среднее | Принцип «сайт опционален»: если мешает — удаляем конфиг, репо работает |
|
||
| VPS временно недоступна | Низкая | Высокое | Опубликованный сайт не зависит от Gitea; GitHub Pages сохраняется как ручной резерв |
|
||
|
||
---
|
||
|
||
## 8. Открытые вопросы
|
||
|
||
1. **Домен.** Использовать GitHub Pages URL или сразу подключить кастомный домен? Можно решить в Спринте 2.
|
||
2. **README.md в корне vs docs/.** Оставляем README.md в корне (GitHub его рендерит) и используем его же как `index.md` для сайта, или делаем симлинк / копию? → Решение в ADR.
|
||
3. **Структура `docs/` директории.** Нужно ли вообще создавать `docs/`, или генератор может работать прямо с корнем репо? → Решение в ADR.
|