deploy(docker): self-init entrypoint (миграции+засев прав) + гайд по TrueNAS

- docker-entrypoint.sh: при старте node migrations-runner (идемпотентно) + seed-permissions только если role_permissions пуста → контейнер поднимается на чистом томе без ручных шагов (сервер раньше fail-fast без миграций). Dockerfile: ENTRYPOINT через tini + entrypoint, нормализация CRLF (sed) + chmod, label BQ-System → LearnSpace. - DEPLOY-TRUENAS.md: пошагово для TrueNAS SCALE (датасет → образ → Custom App compose с host-path томами и JWT_SECRET → авто-миграции → reverse-proxy/HTTPS/TURN → бэкапы), заметка про CORE. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-19 19:53:24 +03:00
parent d63c99cae9
commit f7c5f222a3
3 changed files with 145 additions and 5 deletions
@@ -0,0 +1,118 @@
+# Запуск LearnSpace на TrueNAS
+
+Коротко: **TrueNAS SCALE** (Linux) запускает приложение как **Docker-контейнер** — в репозитории уже
+есть `Dockerfile` и `docker-compose.yml`. **TrueNAS CORE** (FreeBSD) Docker не умеет — там нужен Linux-VM
+или jail с Node (см. конец). Ниже — путь для **SCALE** (рекомендуемый).
+
+Контейнер **самоинициализируется**: при старте применяет миграции БД и при первом запуске засевает права
+(`docker-entrypoint.sh`). Данные (SQLite-БД, загрузки, бэкапы) хранятся в томах, переживают пересоздание.
+
+---
+
+## 1. Подготовка хранилища (dataset)
+
+В TrueNAS создайте датасет под приложение и в нём подпапки для постоянных данных:
+
+```
+Datasets → Add Dataset:  tank/apps/learnspace
+```
+Внутри (через Shell или по SMB) создайте три папки — БД, загрузки, бэкапы:
+```
+/mnt/tank/apps/learnspace/data
+/mnt/tank/apps/learnspace/uploads
+/mnt/tank/apps/learnspace/backups
+```
+Они монтируются в контейнер; их защищают снапшоты/репликация TrueNAS.
+
+## 2. Доставить образ на NAS (3 варианта)
+
+**A. Собрать на машине с Docker и перенести** (без реестра):
+```bash
+# на ПК с Docker, в корне репозитория:
+docker build -t learnspace:latest .
+docker save learnspace:latest | gzip > learnspace.tar.gz
+# скопировать learnspace.tar.gz на NAS (SMB/scp), затем в Shell TrueNAS:
+docker load < /mnt/tank/apps/learnspace/learnspace.tar.gz
+```
+
+**B. Через реестр** (Docker Hub / GHCR / локальный): `docker push <registry>/learnspace:latest`,
+а в compose указать этот `image:`.
+
+**C. Собрать прямо на NAS** (SCALE ElectricEel 24.10+ имеет Docker CLI): склонировать репозиторий в
+датасет и `docker compose build` (см. ниже).
+
+## 3. Развернуть как Custom App (Compose YAML)
+
+TrueNAS SCALE → **Apps → Discover Apps → Custom App → Install via YAML** (на ElectricEel+ это нативный
+docker-compose). Вставьте (правьте пути пула, порт и **обязательно JWT_SECRET**):
+
+```yaml
+services:
+  app:
+    image: learnspace:latest          # из шага 2 (или build: . если собираете на NAS)
+    container_name: learnspace
+    restart: unless-stopped
+    ports:
+      - "3000:3000"                    # снаружи:внутри. Поменяйте левую часть при конфликте
+    volumes:
+      - /mnt/tank/apps/learnspace/data:/app/backend/data
+      - /mnt/tank/apps/learnspace/uploads:/app/backend/uploads
+      - /mnt/tank/apps/learnspace/backups:/app/backups
+    environment:
+      - NODE_ENV=production
+      - PORT=3000
+      - JWT_SECRET=ЗАМЕНИТЕ_на_длинную_случайную_строку   # обязательно! напр. `openssl rand -hex 32`
+      - JWT_EXPIRES_IN=7d
+      - DB_PATH=/app/backend/data/learnspace.db
+      - UPLOADS_DIR=/app/backend/uploads
+      - CLIENT_ORIGIN=https://learn.example.com           # публичный адрес (для CORS); или http://<ip>:3000
+      # необязательно — TURN для видеосвязи за NAT (классы/доска):
+      # - TURN_URL=turn:turn.example.com:3478
+      # - TURN_USER=...
+      # - TURN_PASS=...
+      # необязательно — LLM «Спроси» (Groq и т.п.):
+      # - ASSISTANT_LLM_URL=https://api.groq.com/openai/v1/chat/completions
+      # - ASSISTANT_LLM_KEY=...
+      # - ASSISTANT_LLM_MODEL=llama-3.3-70b-versatile
+```
+
+Сгенерировать секрет: в Shell TrueNAS `openssl rand -hex 32`.
+
+## 4. Первый запуск
+
+При старте entrypoint сам накатит миграции и засеет права — отдельных команд не нужно. Проверьте:
+- **Apps → learnspace → Logs**: должно быть `applying migrations...` → `starting server...` → `Server running on port 3000`.
+- Healthcheck (`/api/health`) станет «healthy» через ~10–30 с.
+
+Откройте `http://<IP_NAS>:3000`. Создайте первого пользователя через регистрацию (или заведите админа —
+скажите, добавлю команду/скрипт сидинга админа).
+
+## 5. HTTPS и домен (рекомендуется)
+
+Порт 3000 — внутренний. Для доступа по домену с HTTPS поставьте reverse-proxy:
+- TrueNAS app **Traefik**/**Nginx Proxy Manager**, либо внешний nginx → проксировать на `<IP_NAS>:3000`.
+- В `CLIENT_ORIGIN` укажите итоговый публичный URL (иначе CORS заблокирует фронт).
+- Для классов/доски (WebRTC) за CGNAT/симметричным NAT нужен TURN-сервер (coturn) — иначе p2p может не подняться.
+
+## 6. Обновление версии
+
+1. Пересоберите образ новой версии (шаг 2) с тем же тегом или новым.
+2. Apps → learnspace → **Edit** (обновите `image:` если тег сменился) → **Update**, либо пересоздайте app.
+3. Данные сохранятся (тома на датасете). Миграции применятся автоматически при старте.
+
+## 7. Бэкапы
+
+Данные в `/mnt/tank/apps/learnspace/{data,uploads}`. Настройте **снапшоты датасета** + при желании
+**репликацию**. SQLite-файл — `data/learnspace.db` (консистентный бэкап лучше делать при остановленном app
+или через снапшот ZFS).
+
+---
+
+## TrueNAS CORE (FreeBSD) — без Docker
+
+CORE не запускает Docker-контейнеры. Варианты:
+- **Linux-VM** в TrueNAS CORE (если включён bhyve) → внутри VM поставить Docker и следовать инструкции SCALE выше.
+- **Jail** с Node 22+: установить node, `npm ci --omit=dev` в `backend/`, прописать env, `npm run migrate &&
+  npm run seed:permissions`, запускать `node src/server.js` под supervisor (pm2/rc.d). node:sqlite требует Node ≥ 22.
+
+> Какой у вас TrueNAS (SCALE или CORE) и версия — подскажу точные шаги под конкретный вариант.