iiEsaywebUI/docs/DEPLOYMENT.md

# Инструкция по развёртыванию iiEasyWeb

Пошаговое развёртывание: Git, Docker, ребрендинг, поиск (SearXNG), воркер Nextcloud (Python).

---

## Требования

- Docker и Docker Compose
- (Опционально) NVIDIA GPU и драйверы — для Ollama
- Доступ к Gitea (например `192.168.88.165:3000`)
- Nextcloud и Authentik — при использовании воркера и OAuth

---

## Архитектура

```
┌─────────────────────────────────────────────────────────────┐
│                    Reverse Proxy (Nginx)                     │
│              *.iieasy.ru (odo.iieasy.ru)                     │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌───────▼────────┐  ┌───────▼────────┐
│  Open WebUI    │  │   Authentik     │  │   Nextcloud    │
│  odo.iieasy.ru │  │ auth.iieasy.ru  │  │next.iieasy.ru  │
└───────┬────────┘  └─────────────────┘  └───────┬────────┘
        │                                         │
        │  ┌──────────────────────────────────────┘
        │  │
        ▼  ▼
┌─────────────────────────────────────────────────────────────┐
│              Docker Network (iieasy-ai)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │  Ollama  │  │  Qdrant  │  │ SearXNG  │                  │
│  │ (GPU)    │  │ (Vector) │  │ (Search) │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │ Python Worker │
                    │ (Nextcloud →  │
                    │  Qdrant Sync) │
                    └───────────────┘
```

---

## 1. Git — отправка кода в репозиторий

**Сервер Gitea:** `192.168.88.165`, веб-интерфейс на порту `3000`.  
**Репозиторий:** `ars/iiEsaywebUI`.

### Что не должно попадать в Git

- `.env`, `worker/.env`
- `worker/.venv`, секретные ключи, токены
- Убедитесь, что в `.gitignore` есть эти пути (в проекте уже настроено).

### Вариант A — SSH

1. Настройте `~/.ssh/config` (при необходимости укажите порт SSH сервера, если не 22):

   ```
   Host 192.168.88.165
     HostName 192.168.88.165
     User git
     Port 22
   ```

2. URL репозитория: `git@192.168.88.165:ars/iiEsaywebUI.git`

### Вариант B — HTTPS с токеном

- URL: `https://192.168.88.165:3000/ars/iiEsaywebUI.git`
- При push: логин `ars`, пароль — **подставьте свой токен из Gitea** (или пароль учётной записи, в зависимости от настроек Gitea). Не храните токен в URL в документации.

### Шаги (если репозиторий ещё не инициализирован)

```bash
cd /home/its/iiEasyWeb
git init
git remote add origin git@192.168.88.165:ars/iiEsaywebUI.git
# или HTTPS: git remote add origin https://192.168.88.165:3000/ars/iiEsaywebUI.git
git add .
git status   # проверьте, что нет .env и секретов
git commit -m "Initial deployment setup"
git branch -M main
git push -u origin main
```

Если ветка по умолчанию на Gitea — `master`, используйте `git push -u origin master`.

---

## 2. Docker — поднятие стека

**Файлы:** корень проекта — `docker-compose.yml`, `.env.example`.

### Шаги

1. **Каталог и конфиг:**

   ```bash
   cd /home/its/iiEasyWeb
   cp .env.example .env
   ```

2. **Редактирование `.env`:**
   - Домены: `DOMAIN_OPENWEBUI`, `DOMAIN_NEXTCLOUD`, `DOMAIN_AUTHENTIK`, при необходимости `DOMAIN_VAULTWARDEN`.
   - Authentik: `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OPENID_CONNECT_ISSUER`.
   - Qdrant — сгенерировать ключ и прописать в `QDRANT_API_KEY`:

     ```bash
     openssl rand -hex 32
     ```

   - Остальное по необходимости (Nextcloud для воркера, Vaultwarden, Ollama). Для GPU: `NVIDIA_VISIBLE_DEVICES=all`.

3. **Запуск:**

   ```bash
   docker compose up -d
   docker compose ps
   ```

4. **Модель Ollama (после старта контейнера ollama):**

   ```bash
   docker exec ollama ollama pull gemma3n:e4b-it-fp16
   docker exec ollama ollama list
   ```

5. **Проверка:** Open WebUI доступен на порту **3001** (маппинг `3001:8080` в `docker-compose.yml`), т.е. `http://localhost:3001` или ваш `DOMAIN_OPENWEBUI`.

---

## 3. Ребрендинг

**Используйте только скрипт:** `scripts/rebrand_safe_final.sh`. Старый `rebrand.sh` может ломать OAuth.

### Медиафайлы

Поместите в каталог `media/`:
- **Обязательно:** `media/logo.png`
- По желанию: `favicon.png`, `logo-dark.svg`, `logo-light.svg`

### Запуск ребрендинга

Контейнер `open-webui` должен быть запущен.

```bash
cd /home/its/iiEasyWeb
sudo ./scripts/rebrand_safe_final.sh
```

### После обновления образа Open WebUI

```bash
docker compose pull
docker compose up -d
sudo ./scripts/rebrand_safe_final.sh
```

### Проверка

Очистите кеш браузера и откройте `http://localhost:3001` или `DOMAIN_OPENWEBUI`.

Подробнее: `QUICK_START.md`, `REBRAND_SOLUTION.md`.

---

## 4. Поиск (SearX / SearXNG)

Поиск уже включён в `docker-compose.yml`: сервис `searxng`, Open WebUI настроен на него (`RAG_WEB_SEARCH_ENGINE=searxng`, `SEARXNG_QUERY_URL=...&format=json`, `ENABLE_WEB_SEARCH=true`).

### Настройка при развёртывании

1. **Секретный ключ SearXNG**  
   В `searxng/settings.yml` замените `CHANGE_ME_SECRET_KEY` на свою строку (любая случайная строка). Иначе в логах возможны предупреждения.

2. **Проверка после старта:**

   ```bash
   docker exec open-webui curl -s "http://searxng:8080/search?q=test&format=json" | head -c 200
   ```

3. **Если появляется ошибка User-Agent (Invalid leading whitespace):**  
   Используйте проверенный скрипт **fix_user_agent_final.sh**. В `docker-compose.yml` для сервиса `open-webui` добавьте:
   - volume: `./scripts/fix_user_agent_final.sh:/fix_user_agent_final.sh:ro`
   - entrypoint: `["/bin/sh", "-c", "sh /fix_user_agent_final.sh && exec /bin/bash /app/start.sh"]`  
   Затем перезапустите: `docker compose restart open-webui`.

4. **Диагностика:**

   ```bash
   sudo ./scripts/diagnose_search.sh
   ```

   При проблемах: `sudo ./scripts/fix_search_complete.sh`.

Подробнее: `SEARXNG_SETUP.md`.

---

## 5. Nextcloud Python (воркер)

Воркер синхронизации Nextcloud → Open WebUI/Qdrant запускается на хосте (не в Docker).

**Каталог:** `worker/`. Файлы: `nextcloud_sync.py`, `.env.example`, `requirements.txt`.

### Переменные окружения

```bash
cd /home/its/iiEasyWeb/worker
cp .env.example .env
```

Заполните в `.env`:
- **Nextcloud:** `DOMAIN_NEXTCLOUD`, `NC_USER`, `NC_APP_PASSWORD`, при необходимости `NC_SCAN_PATHS`.
- **Open WebUI:** `DOMAIN_OPENWEBUI`, `OPENWEBUI_API_KEY` (ключ создаётся в Open WebUI: Settings → Account → API Keys).
- По желанию: `SYNC_INTERVAL`, `MAX_FILE_SIZE`, `LOG_LEVEL`.

**Важно:** для Nextcloud используйте **пароль приложения** (App Password), не основной пароль учётной записи.

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

```bash
pip install -r requirements.txt
python nextcloud_sync.py --once
```

Постоянный режим (daemon):

```bash
python nextcloud_sync.py --daemon
```

### Production (systemd)

Создайте файл `/etc/systemd/system/iieasy-sync.service`:

```ini
[Unit]
Description=iiEasy Nextcloud Sync Worker
After=network.target

[Service]
Type=simple
User=its
WorkingDirectory=/home/its/iiEasyWeb/worker
ExecStart=/usr/bin/python3 /home/its/iiEasyWeb/worker/nextcloud_sync.py --daemon
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

Замените `User=its` и пути при необходимости. Затем:

```bash
sudo systemctl daemon-reload
sudo systemctl enable iieasy-sync
sudo systemctl start iieasy-sync
```

---

## Порядок выполнения

1. **Git** — инициализация репозитория, remote, первый push (без `.env` и секретов).
2. **Docker** — `cp .env.example .env`, правка `.env`, генерация `QDRANT_API_KEY`, `docker compose up -d`, загрузка модели Ollama.
3. Первый вход в Open WebUI (при необходимости настройка Authentik OIDC), создание API ключа в Settings → Account → API Keys.
4. **Ребрендинг** — файлы в `media/`, `sudo ./scripts/rebrand_safe_final.sh`.
5. **Поиск** — правка `searxng/settings.yml` (secret_key), при ошибке User-Agent — entrypoint с `fix_user_agent_final.sh`; при проблемах — `diagnose_search.sh`, `fix_search_complete.sh`.
6. **Nextcloud Python** — настройка `worker/.env`, `pip install -r requirements.txt`, проверка `--once`, затем `--daemon` или systemd.

---

## Замечания

- **Токен/пароль Gitea:** в документации не указывайте токен в открытом виде; используйте «подставить свой токен из Gitea» или SSH.
- **Имя репозитория:** на сервере используется `iiEsaywebUI` (с одной «a») — в URL remote указывайте так же.
- **Порт SSH:** если Gitea слушает SSH на порту не 22 (например 3000), укажите в `~/.ssh/config` для хоста `Port 3000`; URL остаётся `git@192.168.88.165:ars/iiEsaywebUI.git`.