# Развёртывание Proxmox MCP и TrueNAS MCP

Инструкция предназначена для развёртывания стека Docker Compose на TrueNAS-хосте `192.168.31.100`, где также работает Open WebUI.

Состав стека:

- `proxmox-mcp-pve` — Proxmox MCP для сервера `pve`, порт `8811`;
- `proxmox-mcp-kybinka` — Proxmox MCP для сервера `kybinka`, порт `8812`;
- `proxmox-mcp-pve1` — Proxmox MCP для сервера `pve1`, порт `8813`;
- `truenas-mcp` — TrueNAS MCP, порт `8814`.

## 1. Предварительные требования

На хосте TrueNAS должны быть доступны:

- Docker Engine и Docker Compose plugin;
- рабочий каталог `/mnt/ssd/apps/mcp`;
- исходники TrueNAS MCP в каталоге `/mnt/ssd/apps/mcp/truenas`;
- файл `/mnt/ssd/apps/mcp/truenas/Dockerfile`;
- сетевой доступ от Docker-хоста к Proxmox API и TrueNAS API.

Проверьте версии:

```bash
docker --version
docker compose version
```

Перейдите в каталог, где находятся `compose.yaml` и `.env`:

```bash
cd /mnt/ssd/apps/mcp
```

## 2. Подготовка конфигурационных каталогов

```bash
mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}
```

Каждый Proxmox MCP получает собственный `config.json`. Пример для `pve`:

```json
{
  "proxmox": {
    "host": "192.168.31.2",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "openwebui-token",
    "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE"
  },
  "logging": {
    "level": "INFO"
  },
  "security": {
    "dev_mode": true
  }
}
```

Для `kybinka` и `pve1` измените `proxmox.host`, `token_name` и `token_value`.

Права доступа к конфигурациям:

```bash
chmod 700 /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}
chmod 600 /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}/config.json
```

Проверьте JSON до запуска:

```bash
for file in /mnt/ssd/apps/mcp/{pve,kybinka,pve1,truenas}/config.json; do
  [ -f "$file" ] && python3 -m json.tool "$file" >/dev/null && echo "OK: $file"
done
```

> `auth.token_value` — секрет подключения MCP к Proxmox. Он не используется в Open WebUI.

## 3. Подготовка переменных окружения

Скопируйте шаблон:

```bash
cp .env.example .env
chmod 600 .env
```

Сгенерируйте отдельные Bearer-ключи для OpenAPI:

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

Внесите разные значения в:

```dotenv
PROXMOX_PVE_API_KEY=...
PROXMOX_KYBINKA_API_KEY=...
PROXMOX_PVE1_API_KEY=...
TRUENAS_API_KEY=...
```

Не добавляйте `.env` в Git. Файл уже включён в `.gitignore`.

### Адрес публикации портов

В `.env`:

```dotenv
MCP_BIND_ADDRESS=192.168.31.100
```

Это позволяет Open WebUI обращаться к сервисам по LAN-адресу. Если Open WebUI и MCP доступны только локально, используйте `127.0.0.1`. При публикации на LAN-адрес ограничьте входящие соединения firewall-правилом только для хоста Open WebUI.

## 4. Проверка Compose-файла

До запуска выполните:

```bash
docker compose --env-file .env config >/tmp/proxmox-mcp-compose-rendered.yaml
docker compose --env-file .env config --quiet
```

Проверьте, что отрендеренный файл не содержит неожиданных путей или настроек. Не публикуйте его, если в нём присутствуют раскрытые секреты.

Если `truenas/Dockerfile` отсутствует, сборка `truenas-mcp` завершится ошибкой. В этом случае сначала разместите исходники TrueNAS MCP в каталоге `./truenas`.

## 5. Первый запуск

Соберите TrueNAS MCP и запустите весь стек:

```bash
docker compose --env-file .env up -d --build
```

Проверьте состояние:

```bash
docker compose ps
docker compose logs --tail=100 proxmox-mcp-pve
docker compose logs --tail=100 proxmox-mcp-kybinka
docker compose logs --tail=100 proxmox-mcp-pve1
docker compose logs --tail=100 truenas-mcp
```

## 6. Проверка HTTP API

Проверка жизнеспособности Proxmox MCP:

```bash
curl -f http://192.168.31.100:8811/livez
curl -f http://192.168.31.100:8812/livez
curl -f http://192.168.31.100:8813/livez
```

Проверка спецификации OpenAPI:

```bash
curl -f http://192.168.31.100:8811/openapi.json >/tmp/pve-openapi.json
curl -f http://192.168.31.100:8812/openapi.json >/tmp/kybinka-openapi.json
curl -f http://192.168.31.100:8813/openapi.json >/tmp/pve1-openapi.json
```

Проверка Bearer-ключа:

```bash
curl -f \
  -H "Authorization: Bearer ${PROXMOX_PVE_API_KEY}" \
  http://192.168.31.100:8811/health
```

Если endpoint `/health` в используемой версии образа отсутствует, ориентируйтесь на `/livez` и ответ `/openapi.json`.

## 7. Подключение к Open WebUI

Для каждого сервера создайте отдельный External Tool Server:

| Сервис | Базовый URL | OpenAPI |
|---|---|---|
| Proxmox pve | `http://192.168.31.100:8811` | `openapi.json` |
| Proxmox kybinka | `http://192.168.31.100:8812` | `openapi.json` |
| Proxmox pve1 | `http://192.168.31.100:8813` | `openapi.json` |
| TrueNAS MCP | `http://192.168.31.100:8814` | `openapi.json` |

Используйте авторизацию `Bearer` и соответствующий ключ из `.env`.

Важно:

- в URL указывайте только базовый адрес;
- не добавляйте `/openapi.json` в базовый URL;
- не используйте `auth.token_value` из Proxmox `config.json` как Bearer-ключ Open WebUI;
- для каждого сервиса используйте собственный ключ.

## 8. Обновление

Перед обновлением сохраните текущую конфигурацию:

```bash
cp .env .env.backup.$(date +%Y%m%d-%H%M%S)
docker compose config > compose.rendered.backup.yaml
```

Обновите образы и пересоберите TrueNAS MCP:

```bash
docker compose pull
docker compose up -d --build
```

Проверьте состояние после обновления:

```bash
docker compose ps
docker compose logs --since=10m
```

В production рекомендуется заменить `:latest` в `compose.yaml` на конкретный tag или digest образа.

## 9. Откат

Если новая версия работает некорректно:

```bash
docker compose down
docker compose up -d
```

Для полноценного отката необходимо вернуть предыдущую версию image в `compose.yaml`, затем выполнить:

```bash
docker compose pull
docker compose up -d --build
```

## 10. Диагностика

### `Invalid API key`

Проверьте, что Bearer-ключ Open WebUI точно совпадает с переменной соответствующего сервиса:

```bash
docker compose config | grep -E 'PROXMOX_API_KEY|TRUENAS_API_KEY'
```

Не вставляйте вывод этой команды в публичный чат или issue.

### `Connection closed`

Проверьте первичную ошибку в логах:

```bash
docker compose logs --tail=200 proxmox-mcp-pve
```

Затем проверьте:

- доступность Proxmox API с Docker-хоста;
- правильность `host`, `port`, `token_name` и `token_value`;
- существование смонтированного `config.json`;
- соответствие версии OpenAPI-интерфейса и конфигурации Open WebUI.

### Ошибка bind на порт

Проверьте занятые порты:

```bash
ss -ltnp | grep -E ':8811|:8812|:8813|:8814'
```

Измените `MCP_BIND_ADDRESS` или внешние порты в `compose.yaml`.

### Контейнер завершается при включённом hardening

В Compose включены `read_only`, `no-new-privileges` и `cap_drop: ALL`. Если конкретная версия образа требует запись в каталог или capability, проверьте ошибку в логах и ослабляйте только проблемную настройку. Не удаляйте весь hardening без необходимости.

## 11. Безопасность

- Не коммитьте `.env`, реальные `config.json`, API-ключи и пароли.
- Используйте отдельные токены для каждого Proxmox-сервера.
- Минимизируйте ACL токенов Proxmox.
- Для TrueNAS предпочтительно использовать HTTPS и `TRUENAS_VERIFY_SSL=true`.
- `TRUENAS_ENABLE_DESTRUCTIVE_OPS=false` оставляйте включённым, пока destructive-операции не потребуются явно.
- Не публикуйте MCP-порты в Интернет.
- Зафиксируйте версии образов вместо `latest`.
- Регулярно проверяйте логи и свободное место Docker-хранилища.