О проекте

Docwise — корпоративная платформа для работы с документами и знаниями:

• хранение и управление документами;
• чат-интерфейс с поиском по корпоративной базе знаний (RAG);
• контроль доступа на основе ролей и разрешений;
• мульти-тенантность (изоляция данных по организациям).

Документация

• Проект (архитектура, модули, мульти-тенантность): docs/README_PROJECT.md
• RAG (архитектура и принципы): docs/README_RAG.md

Установка и запуск

1. Требования к окружению

Минимальный набор для разработки:

• Git
• Docker + Docker Compose v2 (команда docker compose)
• make (GNU Make)
• доступ к интернету для скачивания Docker‑образов и ML‑моделей (RAG, Docling, Hugging Face и др.)

Для RAG по умолчанию используется режим GPU:

• в файле .env переменная RAG_RUNTIME=gpu (берётся из .env.example)
• для запуска GPU‑режима нужен Docker Runtime с поддержкой GPU (например, nvidia-container-toolkit)

Если GPU недоступен, можно перевести RAG в CPU‑режим (см. раздел 6).

---

2. Общая схема сервисов

Проект разворачивается целиком в Docker через docker compose и Makefile из корня репозитория. Основные сервисы:

• nginx — единая точка входа (HTTP)
• frontend — Vue-приложение (Vite dev server в dev, собранный бандл в prod)
• backend — Laravel-приложение (админка, бизнес-логика, интеграции)
• rag — RAG‑подсистема (FastAPI + воркеры конвейера)
• llm-proxy — OpenAI‑совместимый прокси LLM (используется для маршрутизации моделей и может быть вызван как внешнее API)
• db — PostgreSQL
• qdrant — векторная БД
• redis — очереди/стримы
• speech — сервис синтеза/распознавания речи (Yandex SpeechKit)
• telegram-bot — Telegram‑бот, работающий с backend и speech

---

3. Файлы конфигурации окружения

Файлы окружения .env используются как в dev, так и в prod. На dev они обычно создаются автоматически через make init, на prod — через make env или ручное копирование файлов из .env.example.

Шаблоны:

• корень:
  • .env.example → .env
• backend (Laravel):
  • backend/.env.example → backend/.env
• frontend (Vue):
  • frontend/.env.example → frontend/.env
• RAG:
  • rag/.env.example → rag/.env
• Telegram‑бот:
  • integrations/telegram/.env.example → integrations/telegram/.env
• Yandex SpeechKit:
  • integrations/speech/yandex/.env.example → integrations/speech/yandex/.env
• LLM Proxy:
  • integrations/llm-proxy/config.example.yaml → integrations/llm-proxy/config.yaml

3.1. Корневой .env

Файл: .env (создаётся из .env.example). Ключевые переменные:

• DOCKER_PROJECT_NAME=docwise — имя проекта в Docker (идёт в имена контейнеров)
• RAG_RUNTIME=gpu|cpu — режим работы RAG (GPU по умолчанию)
• HOST_FRONTEND_PORT=8001 — внешний порт HTTP (nginx)
• HOST_BACKEND_PORT=8000 — внутренний порт backend (используется прокси)
• HOST_ADMINER_PORT=8002 — порт Adminer
• HOST_QDRANT_PORT=8003 — порт Qdrant
• HOST_UID, HOST_GID — UID/GID текущего пользователя (подставляются автоматически через make init)

3.2. backend/.env

Файл: backend/.env (создаётся из backend/.env.example). Основное:

• настройки Laravel (APP* , LOG* , CACHE** , SESSION** и др.)
• PostgreSQL (DB_*) — хост db, порт 5432 (контейнер базы из docker-compose.yml)
• Redis (REDIS_*) — хост redis
• URL RAG:
  • RAG_URL=http://rag:8000 — внутренний адрес сервиса RAG
• LLM Proxy:
  • LLM_PROXY_BASE_URL=http://llm-proxy:8317/v1 — base_url OpenAI‑совместимого API (используется RAG)
  • LLM_PROXY_API_KEY — ключ доступа (Bearer)
• интеграция с Yandex LLM:
  • YANDEX_API_URL, YANDEX_API_KEY, YANDEX_FOLDER_ID
• интеграция со SpeechKit:
  • SPEECHKIT_URL=http://speech:8000, SPEECHKIT_TIMEOUT

3.3. frontend/.env

Файл: frontend/.env (создаётся из frontend/.env.example). Основное:

• VITE_ENABLE_PWA, VITE_ENABLE_PWA_DEV — активация PWA для prod/dev
• CHOKIDAR_USEPOLLING, CHOKIDAR_INTERVAL — настройки file‑watcher для Docker/WSL2

Адрес backend и RAG для фронтенда проксируются через nginx, поэтому дополнительно прописывать URL в этом файле обычно не требуется.

3.4. rag/.env

Файл: rag/.env (создаётся из rag/.env.example). Содержит:

• настройки Redis‑стримов (RAG_REDIS_*), директорий данных (RAG_DATA_DIR, RAG_UPLOADS_DIR)
• лимиты загрузок и список поддерживаемых типов файлов (RAG_UPLOAD_*)
• параметры реранкера (ONNX‑модель, кэш)
• настройки Hugging Face, spaCy, Docling, RapidOCR
• размерность эмбеддингов и модель (VECTOR_DENSE_DIMENSIONS, EMBED_MODEL_ID)
• URL собственного API эмбеддингов для воркеров (EMBED_API_URL)
• YANDEX_API_KEY, YANDEX_FOLDER_ID — для LLM‑провайдера

3.5. Интеграции

• Telegram‑бот (integrations/telegram/.env):

  • TELEGRAM_BOT_TOKEN — токен бота
  • BACKEND_API_URL — URL API backend, по умолчанию http://localhost:8001/api
  • SPEECHKIT_API_URL — URL API сервиса речи, по умолчанию http://localhost:8002/api/v1

• Yandex SpeechKit (integrations/speech/yandex/.env):

  • YANDEX_API_KEY, YANDEX_FOLDER_ID — ключ и каталог в Yandex Cloud
  • AUDIO_DIR=/app/audio — путь до каталога с аудио в контейнере

• LLM Proxy (integrations/llm-proxy/config.yaml):

  • api-keys — список ключей доступа к OpenAI‑совместимому API
  • remote-management.secret-key — ключ управления (если нужен доступ к панели)

---

4. Установка dev-окружения с нуля (Docker)

Все команды выполняются из корня репозитория.

4.1. Клонирование репозитория

git clone https://github.com/void-environment/docwise.git
cd docwise

4.2. Проверка/правка шаблонов окружения (опционально)

При необходимости до запуска можно отредактировать:

• .env.example — изменить RAG_RUNTIME (например, на cpu) и порты HOST_*
• backend/.env.example — указать свои значения APP_URL, почтовых настроек и др.
• rag/.env.example — режим работы с Hugging Face (RAG_HF_MODE=offline|online), лимиты и др.
• integrations/*/.env.example — если планируются интеграции (Yandex, Telegram)

Изменения из .env.example будут перенесены в .env при выполнении make init (через цель make env).

4.3. Запуск инициализации

make init

Что делает make init:

1. Создаёт .env файлы из .env.example (корень, backend, frontend, rag, telegram, speech/yandex)
2. Прописывает в корневой .env значения HOST_UID и HOST_GID текущего пользователя
3. Собирает Docker‑образы для всех сервисов (docker compose build)
4. Проверяет и при необходимости устанавливает зависимости:
   • PHP‑зависимости backend (composer install)
   • npm‑зависимости frontend (npm install внутри контейнера)
5. Поднимает контейнеры (docker compose up -d)
6. Генерирует APP_KEY Laravel (php artisan key:generate)
7. Ожидает готовности БД (PostgreSQL)
8. Прогоняет миграции и сиды базы (php artisan migrate --force, db:seed)
9. Очищает кеши и пересобирает автодискавери (php artisan optimize:clear, package:discover)
10. Перезапускает стек (down → up -d)

После успешного выполнения команда завершится без ошибок, а все основные сервисы будут запущены.

4.4. Доступ к приложению

По умолчанию (из .env.example):

• основное веб‑приложение (nginx + frontend + backend):
  • http://localhost:8001
• Adminer (управление PostgreSQL):
  • http://localhost:8002
• Qdrant (векторная БД, HTTP API):
  • http://localhost:8003

Порт 8001 можно изменить в .env через HOST_FRONTEND_PORT до запуска контейнеров.

4.5. Тестовые пользователи/организации после make init

Сиды создают:

• супер-админа (admin@example.com, пароль password)
• несколько организаций (tenants) и пользователей, привязанных к ним (см. TenantSeeder)

---

5. Ежедневная работа (dev)

После того как make init уже был выполнен хотя бы один раз, для обычной разработки достаточно следующих команд.

5.1. Запуск стека

make up

5.2. Остановка стека

make down

5.3. Перезапуск стека

make restart

5.4. Полезные команды для backend

• открыть консоль в контейнере backend:

  make backend-console

• логи backend:

  make backend-logs

• миграции БД:

  make backend-migrate

• сиды БД:

  make backend-seed

• полное обновление схемы + сиды:

  make backend-refresh

• очистка кешей Laravel:

  make backend-clear

5.5. Полезные команды для frontend

• установка npm‑зависимостей (если нужно вручную):

  make frontend-install

• логи frontend:

  make frontend-logs

5.6. Логи RAG и других сервисов

Через Docker напрямую, например:

docker compose logs -f rag
docker compose logs -f db
docker compose logs -f qdrant

---

6. Переключение RAG на CPU

По умолчанию используется GPU‑режим (RAG_RUNTIME=gpu). Для работы на CPU:

1. Остановить стек, если запущен:

   make down

2. В файле .env изменить:

   RAG_RUNTIME=cpu

3. Пересобрать образ RAG (целевой CPU‑вариант):

   make build-rag-cpu

4. Поднять стек заново:

   make up

При необходимости вернуться к GPU‑режиму можно через RAG_RUNTIME=gpu и make build-rag-gpu.

---

7. Установка prod‑окружения с нуля (Docker)

Файл docker-compose.prod.yml описывает продакшен‑окружение. Основные отличия от dev:

• отдельные prod‑образы (docwise-*-:prod)
• отдельные тома для данных (backend_storage, backend_public, documents_data, audio_data и др.)
• health‑checks на всех ключевых сервисах
• логгирование с увеличенными лимитами

7.1. Подготовка кода и .env

На целевом сервере (prod):

git clone https://gitlab.analyticumplus.ru/analyticum/python/docwise.git
cd docwise

Далее нужно создать .env файлы для prod-окружения.

• Через Make (рекомендуется):

  make env

  Эта команда создаст .env, backend/.env, frontend/.env, rag/.env, integrations/telegram/.env, integrations/speech/yandex/.env из соответствующих .env.example без сборки и запуска контейнеров.

• Ручное копирование (если make недоступен):

  cp .env.example .env
  cp backend/.env.example backend/.env
  cp frontend/.env.example frontend/.env
  cp rag/.env.example rag/.env
  cp integrations/telegram/.env.example integrations/telegram/.env
  cp integrations/speech/yandex/.env.example integrations/speech/yandex/.env

После создания файлов обязательно проверьте и измените значения под prod.

7.2. Быстрая инициализация prod (init-prod)

После подготовки .env (см. 7.1) один из самых простых способов запустить prod-окружение «с нуля» — использовать обёртку:

make init-prod

Эта команда последовательно выполняет:

• make build-prod — сборка prod-образов
• make up-prod — запуск prod-стека
• make backend-migrate-prod — прогон миграций в prod
• make backend-seed-prod — прогон сидов в prod

7.3. Сборка prod‑образов

make build-prod

7.4. Запуск prod‑стека

make up-prod

Для остановки:

make down-prod

Перезапуск:

make restart-prod

7.5. Миграции и сиды в prod

Если вы не используете make init-prod или хотите выполнять шаги вручную, миграции и сиды в prod нужно запускать отдельными командами. В отличие от dev-цели make init, в prod-стеке они не выполняются автоматически.

После того как стек поднят (make up-prod), выполните:

make backend-migrate-prod
make backend-seed-prod

---

8. Интеграции: Yandex и Telegram

8.1. Yandex LLM и SpeechKit

Для работы с моделями Yandex необходимо указать в двух файлах (минимум):

• backend/.env:

  • YANDEX_API_KEY
  • YANDEX_FOLDER_ID

• rag/.env:

  • YANDEX_API_KEY
  • YANDEX_FOLDER_ID

Для сервиса речи:

• integrations/speech/yandex/.env:
  • YANDEX_API_KEY
  • YANDEX_FOLDER_ID
  • AUDIO_DIR=/app/audio (обычно оставляется по умолчанию)

После изменения значений перезапустите стек:

make restart

8.2. Telegram‑бот

В файле integrations/telegram/.env задаются:

• TELEGRAM_BOT_TOKEN — токен бота из BotFather
• BACKEND_API_URL — адрес backend API (по умолчанию http://localhost:8001/api)
• SPEECHKIT_API_URL — адрес API сервиса речи (http://localhost:8002/api/v1)

---

9. LLM Proxy (OpenAI‑совместимый API)

llm-proxy поднимается как отдельный сервис и используется RAG‑подсистемой для вызова выбранных моделей. Дополнительно его можно использовать как внешний OpenAI‑совместимый API.

9.1. Доступ через nginx (рекомендуется)

В dev/prod nginx проксирует llm-proxy по префиксу:

• http://localhost:${HOST_FRONTEND_PORT}/api/llm/ → http://llm-proxy:8317/

Примеры эндпоинтов:

• GET /api/llm/v1/models
• POST /api/llm/v1/chat/completions

Аутентификация: Authorization: Bearer <LLM_PROXY_API_KEY>.

9.2. Прямой доступ к контейнеру

Внутри docker‑сети сервис доступен как:

• http://llm-proxy:8317/v1

Этот адрес используется RAG по переменной LLM_PROXY_BASE_URL.

---

10. Справка по командам Makefile

Для просмотра доступных команд в корне репозитория:

make help

Команда выведет список целей Makefile с кратким описанием, включая команды для управления dev/prod‑стеком и полезные утилитарные цели.