Add deploy instructions (TrueNAS SCALE + Dockge build-context caveat)

2026-08-28 17:47:13 +03:00
parent 94a4a8881f
commit 8321db6adf
1 changed files with 55 additions and 0 deletions
@@ -0,0 +1,55 @@
+## truenas-mcp
+
+MCP-сервер для управления TrueNAS через AI-ассистентов, завёрнутый через mcpo
+в OpenAPI-совместимый HTTP-сервис. Внутри используется пакет truenas-mcp-server (PyPI).
+
+Официальный Go-бинарник truenas/truenas-mcp в Docker на TrueNAS SCALE не запустился
+(ошибка exec format error / ENOEXEC) - поэтому используется этот вариант на Python.
+
+### Важно: особенность сборки на TrueNAS SCALE + Dockge
+
+Docker-сервис на TrueNAS SCALE не всегда видит файлы, положенные в папку стека
+после её создания в Dockge. Если положить Dockerfile заранее не в ту папку -
+получишь ошибку "unable to prepare context: path ... not found", даже если путь
+физически существует.
+
+Правильный порядок:
+
+1. В Dockge: "+ Compose" -> вставить compose.yaml из этого репозитория -> Save
+   (пока НЕ Deploy).
+2. Найти физическую папку стека на диске - обычно
+   /mnt/pool/apps/dockge/stacks/имя_стека/
+3. Скопировать в эту папку Dockerfile и config.json из этого репозитория.
+4. Создать в этой же папке .env (см. .env.example) со своим реальным API-ключом
+   TrueNAS.
+5. Только теперь нажать Deploy в Dockge.
+
+### Файлы
+
+- compose.yaml - конфигурация сервиса (порт 8814:8000)
+- Dockerfile - собирает образ на python:3.11-slim, ставит mcpo и truenas-mcp-server
+- config.json - регистрирует truenas-mcp-server как stdio MCP-сервер для mcpo
+- .env.example - шаблон; реальный .env с ключом никогда не коммитить
+
+### Переменные окружения
+
+TRUENAS_API_KEY (в .env) - API-ключ TrueNAS
+TRUENAS_URL - URL TrueNAS, например http://192.168.31.100
+TRUENAS_VERIFY_SSL - false для самоподписанного сертификата
+TRUENAS_ENABLE_DESTRUCTIVE_OPS - false блокирует разрушительные операции
+TRUENAS_LOG_LEVEL - уровень логирования, например INFO
+
+### Проверка после деплоя
+
+docker logs truenas-mcp --tail 15
+
+Должно быть: Successfully connected to: truenas / Uvicorn running on http://0.0.0.0:8000
+
+### Подключение клиентов
+
+- OpenAPI-схема: http://truenas-ip:8814/openapi.json
+- Документация в браузере: http://truenas-ip:8814/docs
+- Open WebUI: Admin Panel -> Settings -> External Tools -> Type: OpenAPI -> URL выше.
+- Claude Desktop: сервис отдаёт OpenAPI, а не MCP Streamable HTTP - Custom Connectors
+  не примет его напрямую. Для Claude Desktop используется локальный запуск того же
+  truenas-mcp-server через uvx в claude_desktop_config.json.