erjemin/2026-etpgrf-site
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add: немного описания

Browse Source
This commit is contained in:
erjemin
2026-10-04 22:32:48 +03:00
parent d0e8ca2e8d
commit 21144eb825
6 changed files with 264 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
NOTE.md
+32
View File
@@ -0,0 +1,32 @@
# Заметки по деплою проекту
В финальном комите перед новой версией (*ТОЛЬ ПОСЛЕ ТЕСТИРОВАНИЯ:) не забываем менять:
- `CHANGELOG.md` делать описание изменений.
- `typograph/templates/typograph/base.html` в шаблоне циферки в подвале
Затем, когда код готов к релизу, нужно обновить версию в `pyproject.toml`:
```shell
poetry version patch
```
Финальный коммит, таким образом, должен включать в себя:
- Обновление `CHANGELOG.md` с описанием изменений.
- Обновление версии в `pyproject.toml` (через `poetry version patch`).
- Обновление шаблона `base.html` (циферки в подвале).
— Обновление в `etpgrf_site/__init__.py`.
- И, конечно же, все изменения, которые были сделаны в коде.
После комита и пуша:
```shell
git add .
git commit -am "Обновление версии для релиза vX.Y.Z"
git push origin main
```
Для запуска деплоя CI/CD, через Gitea Actions, создаем `git tag` и пушим его в репозиторий:
```shell
git tag vX.Y.Z && git push origin vX.Y.Z
```
_prj_blueprint/backend.md
+57
View File
@@ -0,0 +1,57 @@
# Бэкенд: Архитектура и модули
## 1. Django Конфигурация (`etpgrf_site/etpgrf_site/`)
- **`settings.py`**:
- `DEBUG` и `SECRET_KEY` считываются из переменных окружения.
- `ADMIN_URL`: настраиваемый префикс панели администратора (по умолчанию `admin/`).
- База данных: SQLite в `data/db-etpgrf.sqlite3` с `timeout: 20` для надежности при конкурентных запросах.
- Статика: `STATICFILES_DIRS = [BASE_DIR.parent / 'public' / 'static']`, `STATIC_ROOT = BASE_DIR.parent / 'public' / 'static_collected'`.
- Медиа: `MEDIA_ROOT = BASE_DIR.parent / 'media'`, `MEDIA_URL = '/media/'`.
- Защита за прокси: в `not DEBUG` активированы `SECURE_PROXY_SSL_HEADER`, `SECURE_SSL_REDIRECT`, `SESSION_COOKIE_SECURE`, `CSRF_COOKIE_SECURE`, `USE_X_FORWARDED_HOST`, `USE_X_FORWARDED_PORT`.
- **`urls.py`**:
- `/{ADMIN_URL}` -> админка Django.
- `/` -> `typograph.urls` (главная страница типографа, API обработки и статистики).
- `/blog/` -> `blog.urls` (список постов, детальная страница поста).
- `/sitemap.xml` -> карта сайта (`PostSitemap`).
- `/<slug:slug>/` -> ловушка для статических страниц (например, `/about/`, `/privacy-policy/`, `/donate/`).
## 2. Приложение `typograph`
Отвечает за взаимодействие с библиотекой типографирования `etpgrf` и сбор агрегированной аналитики.
### Модели (`typograph/models.py`)
- **`DailyStat`**:
- Агрегированные посуточные показатели (`date` - уникальная дата).
- Метрики активности: `index_views`, `process_requests`, `copy_count`.
- Объемы данных: `chars_in`, `chars_out`, `chars_copied`.
- Производительность: `total_processing_time_ms`, вычисляемое свойство `avg_processing_time_ms`.
- `settings_stats`: JSONField со статистикой популярности опций (языки, кавычки, переносы, висячая пунктуация и т.д.).
### Представления и Эндпоинты (`typograph/views.py`)
- `index` (`/`): главная страница, инкрементирует просмотры `index_views`.
- `process_text` (`/process/`, POST):
- Принимает текст и параметры типографирования из формы.
- Инициализирует `LayoutProcessor`, `Hyphenator`, `Typographer` из пакета `etpgrf`.
- Производит замер времени обработки `time.perf_counter()`.
- Атомарно обновляет счетчики в `DailyStat`.
- Возвращает HTML-фрагмент `typograph/result_fragment.html` и заголовок `X-Processing-Time`.
- `track_copy` (`/track-copy/`, POST): фиксирует факт и длину скопированного в буфер текста.
- `get_stats_summary` (`/stats-summary/`, GET): возвращает компактный HTMX-фрагмент со статистикой для футера.
## 3. Приложение `blog`
Отвечает за публикации, статьи и произвольные статические страницы.
### Модели (`blog/models.py`)
- **`Post`**:
- `post_type`: `B` (Пост блога) или `P` (Страница).
- `title`, `slug` (автоматическая транслитерация через `pytils.translit.slugify` с обработкой коллизий).
- `is_published`, `published_at`, `updated_at`.
- `content` (HTML-разметка), `excerpt` (тизер).
- `image` (обложка для превью и Open Graph).
- SEO-поля: `seo_title`, `seo_description`, `seo_keywords`.
- Метод `get_absolute_url()`: возвращает `/blog/<slug>/` для постов или `/<slug>/` для страниц.
### Представления (`blog/views.py`)
- `post_list` (`/blog/`): список опубликованных статей блога с пагинацией.
- `post_detail` (`/blog/<slug>/`): детальная страница поста с Open Graph мета-тегами и разметкой.
- `page_detail` (`/<slug>/`): отображение статических страниц.
- `sitemaps.py`: генерация `sitemap.xml` по опубликованным записям.
_prj_blueprint/deployment.md
+33
View File
@@ -0,0 +1,33 @@
# Деплой, окружение и регламент релизов
## 1. Конфигурация окружения (.env)
Обязательные переменные:
- `SECRET_KEY`: секретный ключ Django.
- `DEBUG`: `True` для локальной разработки, `False` для продакшена.
- `ALLOWED_HOSTS`: разрешенные хосты через запятую (например, `typograph.cube2.ru,localhost`).
- `CSRF_TRUSTED_ORIGINS`: доверенные URL (например, `https://typograph.cube2.ru,http://localhost:8000`).
- `ADMIN_URL`: путь к панели администратора (например, `mysecretadmin/`).
## 2. Docker и инфраструктура
- **`Dockerfile`**: базовый образ `python:3.13-slim`, установка Poetry, сборка зависимостей, запуск через Gunicorn.
- **`docker-compose.yml`**: конфигурация для разработки (монтирование исходного кода, базы данных и папок статики/медиа).
- **`docker-compose.prod.yml`**: конфигурация для продакшена со связанным сервисом Nginx (`config/nginx/`).
## 3. Чек-лист выпуска релиза (согласно NOTE.md)
Перед созданием релизного тега:
1. Протестировать функционал и миграции.
2. Внести описание изменений в `CHANGELOG.md`.
3. Обновить версии в:
- `pyproject.toml` (командой `poetry version patch` или вручную).
- `etpgrf_site/__init__.py` (при наличии `__version__`).
- `etpgrf_site/typograph/templates/typograph/base.html` (версия библиотеки и версия сайта в футере).
4. Закоммитить изменения:
```bash
git add .
git commit -am "Обновление версии для релиза vX.Y.Z"
git push origin main
```
5. Запустить пайплайн сборки и деплоя через Gitea Actions путем простановки тега:
```bash
git tag vX.Y.Z && git push origin vX.Y.Z
```
_prj_blueprint/frontend.md
+34
View File
@@ -0,0 +1,34 @@
# Фронтенд: Структура и сборка
## 1. Стек и библиотеки
- **HTML / Django Templates:** шаблоны `base.html`, компоненты `typograph/` и `blog/`.
- **CSS:** Bootstrap 5, Bootstrap Icons, кастомные стили `public/static/css/etpgrf.css` с поддержкой темной/светлой темы.
- **Интерактивность:**
- **HTMX:** асинхронные запросы (отправка формы типографирования, динамическое обновление плашки со статистикой без перезагрузки).
- **Alpine.js:** управление состоянием клиентских виджетов и раскрывающихся списков опций.
- **Редактор текста:** CodeMirror 6.
## 2. Сборка фронтенда и вендорных библиотек (`frontend-assembly/`)
- Каталог `frontend-assembly/` управляет сборкой редактора и подготовкой локальных копий всех сторонних библиотек для автономной работы и CDN-fallback:
- `src/editor.js`: инициализация CodeMirror 6, подсветка спецсимволов (`&nbsp;`, `&shy;`, тире, кавычки), интеграция темной/светлой темы.
- `copy-vendor.js`: копирование дистрибутивов Bootstrap 5, Bootstrap Icons (включая шрифты), HTMX и Alpine.js из `node_modules` в `public/static/vendor/`.
- `package.json`: зависимости `@codemirror/*`, `bootstrap`, `bootstrap-icons`, `htmx.org`, `alpinejs`, `esbuild`.
- Команды сборки:
- `npm run build`: выполняет `build:codemirror` (сборка `editor.js`) и `build:vendor` (копирование всех библиотек в `static/vendor/`).
- `npm run build:codemirror`: компилирует бандл в `public/static/codemirror/editor.js`.
- `npm run build:vendor`: экспортирует вендорные CSS/JS/шрифты в `public/static/vendor/`.
- `npm run watch`: отслеживание изменений CodeMirror в реальном времени.
## 3. CDN Fallback стратегия (`base.html`)
- Основные библиотеки подключаются из публичных CDN (jsDelivr, unpkg) для быстрой доставки и кэширования в браузерах.
- При блокировке или недоступности CDN срабатывает автоматический fallback на локальные статические копии:
- **CSS (Bootstrap, Bootstrap Icons):** атрибут `onerror="this.onerror=null;this.href='{% static ... %}';"` на тегах `<link>`.
- **JS (HTMX, Bootstrap Bundle):** проверка глобального объекта (`window.htmx`, `window.bootstrap`) и подгрузка локальной копии через `document.write`.
- **JS (Alpine.js):** `onerror` динамически подключает локальный deferred-скрипт, а также предусмотрена резервная проверка в `DOMContentLoaded`.
## 4. Клиентская статика (`public/static/`)
- `css/etpgrf.css` — основные стили сайта, оформление типографа и блога.
- `js/base.js` — вспомогательные клиентские скрипты (обработка куки-баннера, копирование текста, переключение тем).
- `codemirror/` — собранный esm-бандл редактора.
- `vendor/` — локальные копии сторонних библиотек (`bootstrap`, `bootstrap-icons`, `htmx`, `alpinejs`).
- `svg/` и `img/` — векторные и растровые логотипы для светлой/темной темы и мета-тегов Open Graph.
_prj_blueprint/overview.md
+51
View File
@@ -0,0 +1,51 @@
# Архитектурный обзор проекта ETPGRF Site
## 1. Назначение проекта
**ETPGRF Site** — веб-сервис и интерфейс для онлайн-типографирования текстов на базе библиотеки `etpgrf`, а также контентная платформа (блог, справочные и статические страницы, статистика использования).
## 2. Технологический стек
- **Backend:** Python 3.13+, Django 6.0+, Poetry.
- **База данных:** SQLite 3 (файл `data/db-etpgrf.sqlite3` с увеличенным таймаутом блокировки).
- **Frontend:**
- Bootstrap 5 (CSS, сетка, компоненты, иконки bootstrap-icons).
- Alpine.js (декларативное состояние на клиенте).
- HTMX (динамическая подгрузка фрагментов, отправка форм типографирования, статистика).
- CodeMirror 6 (продвинутый редактор текста с подсветкой спецсимволов/сущностей).
- Сборщик фронтенда: `esbuild` в каталоге `frontend-assembly/`.
- **Инфраструктура & Деплой:**
- Docker & Docker Compose (`docker-compose.yml` для разработки, `docker-compose.prod.yml` для продакшена).
- Nginx (раздача статики `/static/` и медиа `/media/`, SSL-терминация, обратное проксирование к Gunicorn).
- Gunicorn (WSGI-сервер Django).
- CI/CD: Gitea Actions (автосборка Docker-образов по тегам `v*` и деплой).
## 3. Структура директорий
```
2026-etpgrf-site/
├── .github/ # Инструкции для AI и CI
│ └── copilot-instructions.md
├── _prj_blueprint/ # Быстрый контекст и документация архитектуры
├── config/ # Конфигурационные файлы Nginx
│ └── nginx/
├── data/ # Хранилище базы данных SQLite (db-etpgrf.sqlite3)
├── etpgrf_site/ # Исходный код Django
│ ├── manage.py
│ ├── etpgrf_site/ # Корневой модуль конфигурации (settings, urls, wsgi)
│ ├── typograph/ # Приложение типографа (обработка, DailyStat, UI)
│ └── blog/ # Приложение блога и статических страниц
├── frontend-assembly/ # Node.js окружение сборки CodeMirror 6 (esbuild)
├── media/ # Загружаемые медиа-файлы (обложки постов)
├── public/ # Статика проекта
│ ├── static/ # Исходная статика (css, js, img, svg, codemirror)
│ └── static_collected/ # Собранная статика collectstatic
├── Dockerfile # Сборка продакшн-образа
├── docker-compose.yml # Dev-окружение
├── docker-compose.prod.yml # Prod-окружение
├── pyproject.toml # Poetry зависимости и метаданные
├── NOTE.md # Инструкции по релизам и версионированию
└── CHANGELOG.md # История версий
```
## 4. Ссылки на детальные описания
- [Бэкенд и логика приложений](backend.md)
- [Фронтенд и сборка](frontend.md)
- [Деплой, окружение и релизный процесс](deployment.md)
ci-cd.md
+57
View File
@@ -0,0 +1,57 @@
# CI/CD с Gitea Runner
Gitea Runner — это инструмент для выполнения CI/CD задач, интегрированный с Gitea. Он позволяет автоматизировать
процессы сборки, тестирования и развертывания приложений.
В нашем репозии входим в "Настройки" -> "Действия" -> "Ранеры" и создаем новый Runner. Для это получим регистрационный
токен.
## Настройка Gitea Runner на macOS
```shell
docker run -d --restart always \ [±main ●]
-v /var/run/docker.sock:/var/run/docker.sock \
-e GITEA_INSTANCE_URL=https://git.cube2.ru \
-e GITEA_RUNNER_REGISTRATION_TOKEN=здест_полученный_токен \
-e GITEA_RUNNER_REGISTRATION_TOKEN=здесь_вставляем_полученный_токен \
-e GITEA_RUNNER_NAME=mac-mini-runner \
--name gitea-runner \
gitea/act_runner:latest
```
Увидим:
```txt
Unable to find image 'gitea/act_runner:latest' locally
latest: Pulling from gitea/act_runner
6e174226ea69: Pull complete
adcf2c0b73c2: Pull complete
e0c151a1a72f: Pull complete
3333c50851c8: Pull complete
Digest: sha256:0000000000000000000000000000000000000000000000000000000000000000
Status: Downloaded newer image for gitea/act_runner:latest
f000000000000000000000000000000000000000000000000000000000000000
```
## Обновление в продакшен
Наш `.gitea/workflows/docker-publish.yaml` настроен на публикацию Docker образа при создании тега, который начинается
с `v`. Образ собирается на компьютпере разработчика (см. главу Настройка Gitea Runner на macOS) и пакет загружается
в Gitea.
На хостинге работает Docker Stack с нашим проектом. Кроме `etpgrf-site-etpgrf-backend` и `etpgrf-site-etpgrf-nginx`
в нем работает `etpgrf-site-watchtower`, который следит за обновлениями образов на Gitea и если находит обновление, то
получает новый образ и перезапускает контейнер с новым образом.
Т.о. если мы хотим обновить продакшен, нам нужно просто создать новый тег в репозитории:
```shell
git tag v0.1.x
git push origin v0.1.x
```
sudo docker exec -it etpgrf-site-etpgrf-backend-1 python etpgrf_site/manage.py createsuperuser
e-serg
f0b01jLq$eRyID