es-doc

Документация по созданию модов для визуальной новеллы «Бесконечное Лето». Справочник терминов, примеры кода и ресурсы игры в одном месте.

Запуск

pdm install
Copy-Item .env.example .env
pdm run dev    # http://127.0.0.1:8000

Запуск с Docker

# Сборка и запуск контейнеров
docker-compose up --build

# Приложение будет доступно по адресу http://localhost:8005
# TIP: не смотря на то что в main.py порт 8000, в контейнере есть еще nginx который проксирует запрос, а внешний порт у контейнера 8005

Docker Compose настраивает два контейнера:

• web: Python-приложение на порту 8000 (внутренний)
• nginx: Reverse proxy на порту 8005 (внешний)

Ассеты

Ассеты загружаются из репозитория es-doc-assets при сборке образа:

• Продакшн: Ассеты встроены в образ при сборке (см docker-compose.yml \ Dockerfile)
• Разработка: Можно монтировать локальную копию ассетов через volume (см docker-compose.yml \ Dockerfile)

Для разработки с локальными ассетами:

1. Клонируйте репозиторий ассетов: git clone https://github.com/sovue/es-doc-assets.git
2. Раскомментируйте строку в docker-compose.yml:

   volumes:
     - ../es-doc-assets:/app/content

3. Перезапустите контейнеры: docker-compose up --build

Полуавтоматический продакшен-деплой

Продакшен собирается и публикуется через GitHub Actions, а запуск на сервере происходит после ручного одобрения защищённого окружения production. Образ получает неизменяемый тег sha-<commit>, поэтому повторный запуск не зависит от того, какой код сейчас находится в ветке main.

Одноразовая настройка сервера

На сервере нужны Docker Engine с Compose Plugin и каталог, например /opt/es-doc:

mkdir -p /opt/es-doc/deploy
cp .env.production.example /opt/es-doc/.env.production
chmod 600 /opt/es-doc/.env.production

Заполните .env.production: укажите адрес сайта, внешний порт и тот же DEPLOY_PATH, что будет задан в GitHub Secret. Файл остаётся на сервере и не перезаписывается workflow. nginx.conf, compose.production.yaml и deploy/deploy.sh workflow передаёт при каждом запуске.

В GitHub создайте защищённое окружение production, добавьте required reviewer и следующие secrets:

• DEPLOY_HOST, DEPLOY_USER, DEPLOY_PATH;
• DEPLOY_SSH_KEY — приватный ключ отдельного пользователя деплоя;
• DEPLOY_KNOWN_HOSTS — заранее проверенная запись known_hosts для сервера;
• GHCR_USERNAME и GHCR_TOKEN с правом read:packages, если пакет GHCR закрытый.

Выпуск обновления

Откройте Actions → Deploy → Run workflow, выберите app_ref и assets_ref, затем одобрите job в окружении production. Для полностью воспроизводимого контента указывайте в assets_ref полный commit SHA. Workflow строит образ, добавляет SBOM и provenance, публикует его в GHCR и по SSH запускает deploy/deploy.sh на сервере.

После успешного деплоя workflow запускает очистку GHCR. По умолчанию остаются пять последних SHA-релизов, текущий релиз и теги, которые не соответствуют формату sha-*; старые и безымянные версии удаляются. Количество релизов меняется переменной KEEP_RELEASES в .github/workflows/deploy.yml. Очистка выполняется только после успешного запуска приложения, поэтому автоматический rollback не теряет предыдущий образ.

Скрипт блокирует параллельные запуски, проверяет Compose-конфигурацию, ждёт здоровый /healthz перед переключением nginx и сохраняет последний успешный релиз. При неудаче запуска он автоматически возвращает предыдущий тег. Для ручного возврата к релизу, сохранённому перед последним успешным обновлением:

cd /opt/es-doc
./deploy/deploy.sh "$(cat .previous-successful-release)"

Локальный docker-compose.yml остаётся workflow разработки; production использует отдельный compose.production.yaml без bind-mount исходников.

Конфигурация

Локальный .env содержит только параметры этой установки: путь к репозиторию ассетов (ES_DOC_ASSETS_PATH), путь к кэшу (ES_DOC_CACHE_PATH) и флаг отладки (ES_DOC_DEBUG=1). Файл .env игнорируется Git; шаблон находится в .env.example. Старый локальный config.yaml с assets-path и cache-path тоже поддерживается для плавного перехода.

Серверная конфигурация хранится в es-doc-assets/config.yaml вместе с контентом. Там находятся баннеры, тексты ошибок, площадки поддержки и другие настройки, которые должны быть одинаковыми у всех экземпляров сайта.

Баннеры статей

Каждый ключ в разделе banners становится именем Markdown-блока: ключ notice включает синтаксис :::notice, а удаление ключа отключает этот блок. Можно переопределить только нужные поля:

banners:
  stub:
    title: Эта статья — заготовка.
    text: Скоро здесь будет новая статья, мы уже работаем над этим.
    icon: attention
    tone: attention

title — обычный текст, text — Markdown. Приписка автора в статье заменяет стандартный text. Иконка выбирается из встроенных SVG-иконок: info, tip, attention, warning, danger, wip, outdated. Цветовые типы tone: info, tip, attention, warning, danger; цвета берутся из палитры текущей темы.

Для встроенных stub, wip и outdated пропущенные поля используют значения по умолчанию из app/utils/config.py; новый ключ должен содержать все четыре поля. После изменения серверного конфига перезапустите сервер.