mod: описание проекта и развёртывание.

README.md

@@ -1,16 +1,130 @@
-# DicQuo (цитаты и высказывания)
+# DicQuo (Цитаты, Афоризмы и Факты)
 
-Пет-проект ротации цитат и высказываний. Развернут на [dq.cube2.ru](https://dq.cube2.ru).
+**Dicquo** — это коллекция отобранных вручную цитат, оформленных с уважением к типографике. Место для вдумчивого чтения, переосмысления и поиска вдохновения. Проект создан как пространство, где типографика встречается со смыслом, а технологии помогают контенту выглядеть безупречно.
 
-Изначальная цель:
+Основные цели проекта:
-* Испытывать различные типографы (библиотеки и API), разрабатывать и тестировать свои 
+* **Типографика как искусство:** Разработка и тестирование собственных алгоритмов типографирования (висячая пунктуация, неразрывные пробелы, правильные тире) из библиотеки `tpgrf` (доступен в [GitHub](https://github.com/erjemin/etpgrf), [GitVerse](https://gitverse.ru/erjemin/etpgrf) и self-hosted [Cube2](https://git.cube2.ru/erjemin/2025-etpgrf)).
-  типографы и правила типографирования.
+* **SEO-эксперименты:** Исследование влияния микроразметки, мета-тегов и семантической верстки на индексацию поисковыми системами.
-* Испытать, как содержание отдельных атрибуты (meta, keywords, description и т.п.)
+* **Технологический стек:** Современный Django, Docker, CI/CD и автоматизация деплоя.
-  влияют на поисковую выдачу.
 
-[Инструкция по развертыванию на хостинге c CGI Passenger](deploy_to_dreamhost.md)
+Развернут на [dq.cube2.ru](https://dq.cube2.ru).
 
-## ToDo?
+---
+
+## Структура файлов на сервере (Production)
+
+После правильного развертывания, папка проекта на сервере (например, `~/docker-apps/dicquo/`) должна выглядеть так:
+
+```text
+dicquo/
+├── docker-compose.yml       # Переименованный docker-compose.prod.yml из этого репозитория (запускает контейнеры)
+├── .env                     # Файл с переменными окружения и секретами (не пушить в git!)
+├── database/                # Папка для базы данных (Persistent Volume)
+│   ├── db.sqlite3           # Фактический файл базы данных
+├── media/                   # Папка с медиа-файлами (Persistent Volume)
+│   ├── img2/                # Картинки для цитат (доступны через Nginx)
+│   └── errors/              # Картинки для страниц ошибок (404, 500)
+└── config/                  # Папка для конфигураций (Генерируется контейнером)
+    └── nginx/
+        ├── dq-app--external-nginx.conf  # Конфиг для внешнего Nginx (скопируется из контейнера при первом запуске)
+        └── nginx_dq.conf.example        # Образец конфига для внешнего Nginx (не используется в продакшене)
+```
+
+---
+
+## Развёртывание (Deployment)
+
+Проект полностью упакован в Docker и разворачивается с помощью `docker compose`. Ниже приведена инструкция для развертывания на чистом Linux-сервере (Ubuntu/Debian, архитектуры AMD/ARM).
+
+### 1. Подготовка структуры
+
+Создайте директорию для проекта (например, в домашней папке пользователя) и необходимые подпапки для persistent-данных:
+
+```bash
+mkdir -p ~/docker-apps/dicquo
+cd ~/docker-apps/dicquo
+mkdir -p database media config
+```
+
+### 2. Файлы конфигурации
+
+Вам понадобятся два файла из репозитория (или их содержимое):
+1.  **`docker-compose.prod.yml`** -> сохраните его на сервере как `docker-compose.yml`.
+2.  **`.env`** -> создайте на основе `.env.sample`, заполнив секретами для продакшена.
+
+**Важные переменные в `.env`:**
+*   `HOST_PROJECT_PATH`: Полный путь к папке проекта на хосте (например, `/home/username/docker-apps/dicquo`). Используется для корректной генерации конфига Nginx.
+*   `DJANGO_ALLOWED_HOSTS`: Список доменов через запятую (например, `dq.cube2.ru,127.0.0.1`).
+
+### 3. Перенос данных (Опционально)
+
+Если вы мигрируете с dev-окружения или другого сервера, можно просто скопировать файлы базы данных и медиа.
+
+Скопируйте файл базы `database/db.sqlite3` и содержимое папки `media/` в соответсвующие папки на сервере.
+
+### 4. Настройка прав доступа (Permissions) ⚠️
+
+Это **критически важный этап**.
+1.  Docker-контейнер (с нашим бэкендом Django и Gunicorn) должн иметь доступ к примонтированным папкам.
+2.  Внешний Nginx (на хосте) должен иметь доступ к статике и медиа.
+
+**Права на папки проекта:**
+```bash
+# Разрешаем запись в базу и медиа для всех (самый простой способ избежать проблем с UID внутри Docker)
+sudo chmod 777 database
+sudo chmod 666 database/db.sqlite3
+sudo chmod -R 755 media
+```
+
+**Права на родительские директории (Pass-through):**
+Если проект лежит в домашней папке пользователя (`/home/username/...`), то Nginx (пользователь `www-data`) по умолчанию **не сможет** туда попасть. Нужно разрешить "проход" (execute) для всех пользователей по пути к проекту:
+
+```bash
+# Разрешаем "проход" через домашнюю папку (чтение файлов при этом остается закрытым, только доступ к известным путям)
+chmod o+x /home/username
+chmod o+x /home/username/docker-apps
+chmod o+x /home/username/docker-apps/dicquo
+```
+> *Без этого шага Nginx будет выдавать 403 Forbidden на картинки и статику.*
+
+### 5. Запуск
+
+```bash
+docker compose up -d
+```
+При первом запуске контейнер автоматически:
+*   Применит миграции.
+*   Соберет статику.
+*   Сгенерирует конфиг для Nginx в папке `config/nginx/`.
+
+### 6. Настройка Nginx и SSL
+
+1.  **Подключение конфига:**
+    Создайте симлинк на сгенерированный конфиг:
+    ```bash
+    sudo ln -s /home/username/docker-apps/dicquo/config/nginx/dq-app--external-nginx.conf /etc/nginx/sites-enabled/dq-app.conf
+    ```
+2.  **Проверка и релоад:**
+    ```bash
+    sudo nginx -t
+    sudo systemctl reload nginx
+    ```
+3.  **Получение SSL сертификата (Certbot):**
+    ```bash
+    sudo certbot --nginx -d dq.cube2.ru
+    ```
+
+---
+
+## Разработка (Dev)
+
+Для локального запуска используется `docker-compose.yml` (он же dev-версия).
+```bash
+docker compose up --build
+```
+Проект будет доступен по адресу: http://127.0.0.1:8008
+
+## ToDo
 
 * В будущем, возможно, сделать API для предоставления цитат вешним потребителям
   (по темам, авторам и т.п.).