infra/tasks/grimmory-deployment-plan.md

# План развертывания Grimmory

## Целевая архитектура

- Отдельный unprivileged LXC `grimmory` на `cloud-pc`.
- Итоговые значения: CTID `149`, IP `192.168.1.34`. Первоначальный `.33` оказался занят после создания LXC.
- RootFS на storage `data`, первоначально `64 GB` с возможностью расширения.
- Ресурсы: `2 vCPU`, `4 GB RAM`, `1 GB swap`.
- Docker с `fuse-overlayfs` внутри LXC.
- Docker Compose: Grimmory и MariaDB.
- Публичный адрес: `https://books.ada-dev.ru`.
- Книги и данные находятся внутри диска LXC.
- Daily PBS snapshot всего CT.
- Offsite restic: дамп MariaDB, конфигурация и `/app/data`, но не книги.
- Образы фиксируются на версиях:
  - `grimmory/grimmory:v3.2.4`;
  - `lscr.io/linuxserver/mariadb:11.4.8`.

Размер диска нужно скорректировать до развертывания, если текущая библиотека уже приближается к 40-50 GB.

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

1. Проверить, что CTID `149` свободен:
   - в Proxmox API;
   - в `pct list` на обоих узлах;
   - в PBS среди исторических VMID.
2. Проверить IP `192.168.1.34`:
   - отсутствие в inventory;
   - отсутствие DHCP reservation;
   - отсутствие ответа на ARP/ping;
   - отсутствие DNS-записи с другим назначением.
3. Проверить емкость `cloud-pc:data`.
4. Проверить работоспособность PBS datastore и последнего backup job `cloud-pc`.
5. Проверить возможность создать DNS-запись `books.ada-dev.ru`.
6. Зафиксировать ожидаемый объем существующей коллекции и темп роста.
7. Получить digest образов после выбора версий. В первой итерации допустим pinned tag; digest предпочтительнее для полностью воспроизводимого состояния.

Проверка должна завершиться без создания LXC. При конфликте CTID/IP выбрать следующие свободные значения и использовать их согласованно во всех файлах.

## 2. Inventory

Изменить `ansible/inventory/hosts.yml`:

- добавить `grimmory` в `lxc_infra`;
- указать `ansible_host: 192.168.1.34`;
- указать `expected_lan_ip`;
- указать `ansible_user: root`;
- использовать существующий ProxyJump через `ru-vps`;
- добавить в `monitoring_exporters`, если Node Exporter разворачивается сразу.

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

```bash
ansible-inventory --graph
ansible-inventory --host grimmory
```

Edge cases:

- не использовать IP за пределами маршрутизируемого service range `.5-.40`;
- убедиться, что имя `grimmory` разрешается Ansible именно в новый IP;
- не добавлять host в inventory до выбора окончательных CTID/IP во всех playbooks.

## 3. Provisioning LXC

Создать `ansible/playbooks/pve-grimmory.yml`, используя роль `pve_lxc`.

Параметры:

```yaml
pve_lxc_vmid: 149
pve_lxc_node: cloud-pc
pve_lxc_hostname: grimmory
pve_lxc_ip: 192.168.1.34/24
pve_lxc_gateway: 192.168.1.1
pve_lxc_storage: data
pve_lxc_disk: 64
pve_lxc_cores: 2
pve_lxc_memory: 4096
pve_lxc_swap: 1024
pve_lxc_unprivileged: true
pve_lxc_features:
  - nesting=1
  - keyctl=1
```

Дополнительно настроить Docker-in-LXC по существующему паттерну:

- разрешить `/dev/fuse`;
- добавить bind устройства `/dev/fuse`;
- перезапустить LXC только при изменении его PVE-конфигурации;
- дождаться SSH;
- проверить наличие пользовательского SSH-ключа.

Текущая роль `pve_lxc` не управляет `/dev/fuse`, поэтому эти задачи остаются в playbook, аналогично существующим Docker LXC.

Проверки:

```bash
ansible-playbook --syntax-check playbooks/pve-grimmory.yml
ansible-playbook playbooks/pve-grimmory.yml --check
```

`--check` для Proxmox API не гарантирует полноценной симуляции, поэтому его результат использовать только как дополнительную проверку.

После создания проверить:

- `pct status 149`;
- unprivileged mode включен;
- rootfs действительно находится на `data`;
- `onboot=1`;
- SSH работает через ProxyJump;
- `/dev/fuse` существует внутри LXC;
- повторный запуск playbook не создает изменений.

## 4. Docker Runtime

Внутри LXC установить:

- `docker.io`;
- Docker Compose v2, если доступен как `docker-compose-plugin`;
- `fuse-overlayfs`;
- `ca-certificates`;
- `curl`;
- `mariadb-client` для backup/restore-проверок;
- `prometheus-node-exporter`.

Настроить `/etc/docker/daemon.json`:

```json
{
  "storage-driver": "fuse-overlayfs"
}
```

Проверить:

```bash
docker info
docker compose version
docker run --rm hello-world
```

Критерий успеха: Docker сообщает `fuse-overlayfs` как storage driver и переживает перезапуск LXC.

## 5. Persistent Data

Создать структуру:

```text
/opt/grimmory/
├── compose.yml
├── .env
├── data/
├── books/
├── bookdrop/
├── mariadb/
└── backup-staging/
```

Назначение:

- `data` -> `/app/data`;
- `books` -> `/books`;
- `bookdrop` -> `/bookdrop`;
- `mariadb` -> `/config`;
- `backup-staging` -> временные согласованные дампы.

Права каталогов должны соответствовать `APP_USER_ID`, `APP_GROUP_ID`, MariaDB `PUID/PGID`.

Edge cases:

- `bookdrop` не является библиотекой: после успешного импорта исходники удаляются оттуда;
- не размещать важные необработанные оригиналы только в `bookdrop`;
- не вкладывать bind mounts друг в друга;
- не использовать `DISK_TYPE=NETWORK`, поскольку файлы находятся на локальном rootfs;
- оставлять минимум 15-20% диска свободным: импорт и обработка могут временно удваивать размер книги;
- учитывать крупные PDF/CBR и возможные heap dump при OOM.

## 6. Compose

Управлять двумя контейнерами через Compose, поскольку Grimmory зависит от MariaDB. Для этого сервиса Compose логичнее отдельных systemd `docker run`.

Основные параметры:

- `DISK_TYPE=LOCAL`;
- `TZ` соответствует HomeLab;
- `ALLOWED_ORIGINS=https://books.ada-dev.ru`;
- MariaDB доступна только во внутренней Docker network;
- наружу публикуется только Grimmory `6060`;
- порт привязывается к LAN IP LXC, а не `0.0.0.0`, если Compose это позволяет;
- healthcheck использует `/api/v1/healthcheck`;
- `restart: unless-stopped`.

Создать systemd unit-обертку для:

```bash
docker compose -f /opt/grimmory/compose.yml up -d --remove-orphans
```

Не использовать `--pull always`: обновление должно быть отдельной контролируемой операцией.

Секреты:

- случайные отдельные пароли `DB_PASSWORD` и `MYSQL_ROOT_PASSWORD`;
- `.env` с mode `0600`;
- реальные значения не добавляются в Git;
- `.env.example` содержит только имена переменных и фиктивные значения;
- пароль первого администратора создается вручную через UI.

Проверки:

```bash
docker compose config
docker compose pull
systemctl start grimmory
docker compose ps
docker compose logs
curl -fsS http://127.0.0.1:6060/api/v1/healthcheck
```

Критерии:

- оба контейнера healthy;
- MariaDB не публикует порт на LAN;
- после рестарта LXC оба контейнера возвращаются в healthy;
- логи не содержат Flyway errors, authentication failures и циклических рестартов.

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

1. Открыть сервис сначала по LAN.
2. Создать локального администратора.
3. Сохранить пароль в password manager.
4. Отключить неиспользуемую публичную регистрацию.
5. Создать отдельного обычного пользователя для чтения, если административная учетная запись не должна использоваться на BOOX.
6. Включить OPDS.
7. Создать отдельные OPDS credentials.
8. Выдать пользователю разрешение `Access OPDS`.
9. Создать тестовую библиотеку в `/books`.
10. Импортировать одну тестовую EPUB через BookDrop.

Важно: OPDS credentials отделены от обычного логина Grimmory. Пароль OPDS после создания нельзя получить повторно.

## 8. Reverse Proxy

Создать `ansible/playbooks/reverse-proxy-grimmory.yml` по паттерну Gitea/Vaultwarden.

Caddy site:

```caddy
books.ada-dev.ru {
    reverse_proxy 192.168.1.34:6060
}
```

Caddy автоматически поддерживает WebSocket upgrade, но это нужно проверить для `/ws`.

Не добавлять дополнительный Caddy Basic Auth: он конфликтует с Basic Auth OPDS.

Проверки до переключения DNS:

- Caddy может достучаться до `192.168.1.34:6060` через OpenVPN;
- upstream healthcheck возвращает `2xx`;
- Caddyfile проходит `caddy validate`;
- конфигурация действительно смонтирована в контейнер Caddy.

После DNS:

```bash
curl -fsS https://books.ada-dev.ru/api/v1/healthcheck
```

Дополнительно проверить:

- валидную цепочку TLS;
- WebSocket `/ws`;
- правильные внешние `Host`, scheme и port;
- отсутствие redirect на внутренний `http://192.168.1.34:6060`;
- загрузку файла размером больше стандартного proxy limit;
- доступ с мобильной сети, а не только из домашнего LAN.

## 9. OPDS и BOOX Go 7

Каталог:

```text
https://books.ada-dev.ru/api/v1/opds
```

Настроить в NeoReader:

- URL корневого каталога;
- отдельный OPDS username/password;
- HTTPS;
- без второго слоя proxy-аутентификации.

Тестовый сценарий:

1. Каталог открывается.
2. Отображаются разделы и обложки.
3. Работает поиск.
4. EPUB скачивается.
5. Книга открывается в NeoReader.
6. Кириллица в названии, авторе и описании отображается корректно.
7. Повторная загрузка не создает поврежденный файл.
8. Проверить EPUB, PDF и FB2 отдельно.
9. Проверить работу из домашнего Wi-Fi и внешней сети.
10. Проверить поведение после смены OPDS-пароля.

Позиция чтения NeoReader обратно в Grimmory через OPDS не синхронизируется. Это ожидаемое поведение, а не дефект сервера.

## 10. Firewall

Минимальная политика:

- SSH `22` только из LAN и OpenVPN;
- `6060` только из LAN/OpenVPN и от нужного reverse-proxy маршрута;
- MariaDB не публикуется;
- остальные входящие соединения запрещены.

Edge case: Docker published ports могут обходить UFW. Поэтому проверить фактические nftables/iptables rules и доступ к `6060` с нежелательных сегментов, а не полагаться только на вывод `ufw status`.

Публично сервис должен быть доступен только через Caddy на `ru-vps`, не через router port-forward.

## 11. Monitoring

Добавить:

- Node Exporter target `192.168.1.34:9100`;
- LAN blackbox HTTP probe `/api/v1/healthcheck`;
- публичный HTTPS probe `https://books.ada-dev.ru/api/v1/healthcheck`;
- TLS expiry check;
- базовые алерты по availability, CPU, RAM, disk и backup freshness.

Не считать один health endpoint достаточным. Он может отвечать при частично неисправной функции OPDS.

Добавить синтетическую OPDS-проверку:

- Basic Auth тестового monitoring-пользователя;
- ответ `200`;
- ожидаемый OPDS content type;
- корректный XML/Atom;
- секреты только из runtime env, не из шаблона в Git.

Если хранить OPDS credential в monitoring нежелательно, ограничиться публичным healthcheck и ручным OPDS smoke test после обновлений.

## 12. PBS Backup

Добавить CTID в:

- `ansible/playbooks/pve-backup-jobs.yml`, job `homelab-pbs-daily-cloud`;
- `ansible/roles/backup_audit/defaults/main.yml`.

Сохранить исключение Docker merged layers:

```text
/var/lib/docker/fuse-overlayfs/*/merged
```

Проверки:

1. Применить backup job.
2. Запустить первый backup вручную.
3. Убедиться, что snapshot завершен без warnings.
4. Проверить наличие VMID `149` в PBS.
5. Проверить прохождение backup audit.
6. Проверить размер backup: слишком маленький может означать ошибочное исключение данных.
7. Выполнить тестовое file-level восстановление нескольких файлов.
8. Запланировать полный restore drill в отдельный временный CTID.

PBS snapshot MariaDB считается crash-consistent, но не заменяет логический dump.

## 13. Offsite Restic

Offsite должен содержать:

- согласованный `mariadb-dump`;
- `/opt/grimmory/data`;
- `compose.yml`;
- зашифрованную или отдельно защищенную конфигурацию;
- manifest с версиями Grimmory и MariaDB.

Не включать:

- `/opt/grimmory/books`;
- `/opt/grimmory/bookdrop`;
- `/opt/grimmory/mariadb` как raw-copy работающей БД;
- Docker layers;
- временные heap dump и cache.

Для дампа:

- использовать `mariadb-dump --single-transaction`;
- сначала писать во временный файл;
- проверять exit code;
- атомарно переносить завершенный dump в staging;
- только после этого запускать restic;
- удалять старый staging после успешного snapshot.

Расширить существующий restic-паттерн MariaDB-aware логикой, а не использовать SQLite backup helper.

Проверки:

- `mariadb` может прочитать dump;
- restic snapshot содержит dump и `/app/data`;
- backup audit отслеживает профиль Grimmory;
- выполнить пробное восстановление в отдельную временную MariaDB;
- убедиться, что восстановленная схема проходит Flyway startup на той же версии Grimmory.

## 14. Обновления

Обновлять только явно, например `v3.2.4 -> v3.2.5`.

Процесс:

1. Прочитать release notes и migration warnings.
2. Проверить свободное место.
3. Сделать MariaDB dump.
4. Сделать offsite restic snapshot.
5. Убедиться в наличии свежего PBS backup.
6. Изменить pinned image tag/digest.
7. Pull и restart.
8. Проверить Flyway logs.
9. Проверить health, UI, BookDrop и OPDS с BOOX.
10. Зафиксировать версию в документации.

Не выполнять code-only downgrade после применения Flyway migration. Для отката возвращать одновременно старый image и pre-upgrade backup базы.

## 15. Edge Cases

Обязательно проверить:

- заполнение rootfs во время массового импорта;
- дубликаты и одинаковые ISBN;
- книги без ISBN;
- кириллические имена и длинные пути;
- два файла одной книги в разных форматах;
- поврежденный EPUB/CBR;
- файлы больше 1 GB;
- cross-filesystem BookDrop move;
- перезапуск во время импорта;
- падение MariaDB во время обработки;
- недоступность Google Books/Open Library/Amazon;
- истечение TLS;
- смена внешнего домена;
- потеря OPDS-пароля;
- потеря admin-пароля;
- OOM и появление большого heap dump;
- несовместимая Flyway migration;
- неожиданное изменение floating Docker tag;
- частичный backup: БД без `/app/data` либо наоборот;
- восстановление БД с файлами библиотеки другого состояния.

## 16. Финальная приемка

Развертывание считается завершенным, когда:

- Ansible запускается повторно без изменений;
- LXC автоматически стартует;
- контейнеры healthy после reboot;
- MariaDB не доступна из LAN;
- HTTPS и WebSocket работают;
- NeoReader открывает OPDS и скачивает тестовые книги;
- импорт через BookDrop проходит полностью;
- Node Exporter и blackbox targets находятся в состоянии `UP`;
- создан и проверен PBS backup;
- создан и тестово восстановлен restic snapshot;
- секреты отсутствуют в Git diff;
- Obsidian-документация обновлена.

## 17. Ожидаемые файлы

Основные изменения:

- `ansible/inventory/hosts.yml`;
- `ansible/playbooks/pve-grimmory.yml`;
- `ansible/playbooks/reverse-proxy-grimmory.yml`;
- `ansible/playbooks/pve-backup-jobs.yml`;
- `ansible/roles/backup_audit/defaults/main.yml`;
- `ansible/playbooks/offsite-restic-yadisk.yml`;
- `ansible/playbooks/backup-audit.yml`;
- `ansible/roles/monitoring_server/templates/prometheus.yml.j2`;
- возможно `ansible/roles/monitoring_blackbox/templates/push-metrics.sh.j2`;
- `ansible/.env.example`, только если потребуются новые runtime secrets.

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

- `Notes/Текущее состояние HomeLab после миграции на Proxmox.md`;
- `Log.md`;
- `Context.md`;
- при необходимости `HomeLab.md`.

## 18. Открытый параметр

Перед реализацией подтвердить `64 GB` как начальный размер диска или выбрать его по текущему объему коллекции.

Решение: текущая коллекция меньше `20 GB`, начальный rootfs оставлен `64 GB`.

## Журнал выполнения

### 2026-07-28 — preflight и проектные решения

- Прочитаны актуальные HomeLab notes и существующие Ansible-паттерны LXC, Caddy, monitoring, PBS и restic.
- CTID `149` отсутствует в `pct list` на `cloud-pc` и `mini-pc`, а также среди исторических snapshot в PBS.
- IP `192.168.1.33` отсутствует в inventory и AdGuard config, не отвечает на ping, ARP-состояние с `cloud-pc` — `INCOMPLETE`; пользователь подтвердил отсутствие DHCP reservation.
- Storage `cloud-pc:data` активен: доступно около `836 GB`, занято `3.67%`.
- PBS storage и datastore `pbs` активны; последние snapshots текущих cloud-pc CT созданы `2026-07-27`.
- `books.ada-dev.ru` уже разрешается в `157.22.231.198` (`ru-vps`); случайное имя в зоне не разрешается, поэтому это не wildcard. До добавления Caddy site TLS handshake не завершается.
- Подтверждены `grimmory/grimmory:v3.2.4` и `lscr.io/linuxserver/mariadb:11.4.8`; выбраны OCI index digests `sha256:dfa7afdfcf25d649fd664497a62385dd00cd9678c37546e182c172e41c8e80cb` и `sha256:91de7f701bc7fc3a424b81beafca7a7c6c4c5b7c8be6afd2ae148698695c0b0c`.
- Rootfs подтвержден как `data:64`, timezone — `Europe/Moscow`.
- Пароли MariaDB будут случайно созданы один раз внутри LXC и сохранены только в `/opt/grimmory/.env` с mode `0600`.
- В первой итерации автоматизируются health/TLS probes; OPDS smoke test остается ручным после создания credentials.
- Offsite audit первой итерации: атомарный MariaDB dump, проверка наличия dump в snapshot и `restic check`; автоматический restore в MariaDB отложен.
- Первый apply остановился до создания из-за quoting условия VMID guard; второй — из-за отсутствия прямого маршрута к Proxmox API. Для API использован временный SSH local-forward через `ru-vps`.
- После создания CT выяснился IP conflict: с `mini-pc` адрес `.33` резолвился как `YandexStationMini_1DD2.loc` и отклонял TCP/22, тогда как локальный bridge `cloud-pc` видел LXC. Выбран следующий адрес `192.168.1.34`; он не отвечает с обоих PVE-узлов, ARP — `INCOMPLETE`, DNS отсутствует.

### 2026-07-28 — реализация и автоматическая приёмка

- Создан unprivileged LXC `grimmory` CT `149` на `cloud-pc`: `192.168.1.34/24`, `data:64`, 2 vCPU, 4096 MB RAM, 1024 MB swap, `onboot=1`, `nesting=1`, `keyctl=1`, `/dev/fuse`.
- Из-за ограничений API token роль `pve_lxc` используется в create-only mode для Grimmory; VMID guard запрещает менять чужой CT, а network/keyctl/FUSE идемпотентно управляются через `pct` на PVE node.
- Установлены Docker Compose v2 `2.26.1`, Docker `26.1.5`, `fuse-overlayfs`, MariaDB client, Node Exporter и UFW. Docker подтвердил storage driver `fuse-overlayfs`.
- Случайные DB passwords созданы один раз внутри LXC; `/opt/grimmory/.env` имеет mode `0600`, значения не выводились и не добавлялись в Git.
- Compose запустил pinned Grimmory `v3.2.4` и MariaDB `11.4.8`; первый startup применил 142 Flyway migrations и занял около 6 минут. Health wait увеличен до 10 минут.
- После reboot LXC оба контейнера вернулись в `healthy`; MariaDB не слушает host/LAN port, Grimmory привязан к `192.168.1.34:6060`.
- UFW ограничивает SSH/`6060` LAN и OpenVPN, `9100` разрешён только от monitoring LXC. Отдельная `GRIMMORY-FILTER` chain в `DOCKER-USER` закрывает обход UFW через Docker published port.
- Caddy site применён. Проверены public health `200`, сертификат Let's Encrypt до `2026-10-26` и WebSocket/STOMP Upgrade `101` на `/ws`.
- Prometheus targets: Node Exporter `up=1`, LAN health `probe_success=1`, public Grimmory probe `probe_success=1`; TLS expiry покрыт существующим alert.
- CT `149` добавлен в `homelab-pbs-daily-cloud` и PBS audit. Первый PBS backup `ct/149/2026-07-28T14:47:32Z` успешен, размер `2583749785` bytes; audit success, file-level restore трёх объектов проверен.
- Ограничение PBS: storage `data` не поддерживает native LXC snapshots, поэтому job с mode `snapshot` автоматически перешёл в `suspend`; фактическая пауза гостя составила около 1 секунды.
- Создан restic snapshot `a3b012ab` в Yandex Disk. Включены atomic MariaDB dump, `/opt/grimmory/data`, Compose, manifest и зашифрованная restore-конфигурация; books/BookDrop/raw MariaDB исключены. `restic check` и restore непустого `grimmory.sql` прошли.
- Повторные runs `pve-grimmory.yml`, `reverse-proxy-grimmory.yml`, `pve-backup-jobs.yml`, Grimmory offsite/audit и limited monitoring завершились с `changed=0`.
- Обновлены Obsidian current state, `Log.md` и `Context.md`.
- Reverse DNS для `.34` содержит stale имя телефона, но ARP на обоих PVE nodes показывает MAC LXC `bc:24:11:43:75:31`. Нужно исключить `.34` из DHCP pool или закрепить reservation, чтобы предотвратить будущий конфликт.

### Требует участия пользователя

- Создать первого локального администратора и сохранить пароль в password manager.
- Отключить public registration, создать обычного reader-пользователя.
- Создать библиотеку `/books`, выполнить тестовый BookDrop import.
- Включить OPDS, создать отдельные OPDS credentials и выдать `Access OPDS`.
- Проверить EPUB, PDF и FB2 на BOOX Go 7 через Wi-Fi и внешнюю сеть.
- После создания OPDS пользователя решить, добавлять ли credential в synthetic monitoring; сейчас OPDS smoke test ручной.
- Создать DHCP reservation/exclusion для `192.168.1.34`.
- Полный restore drill CT и восстановление dump во временную MariaDB остаются отдельной плановой операцией; file-level restore и dump restore-from-restic уже проверены.

### 2026-07-28 — Caddy KOReader и OPDS compatibility

- `reverse-proxy-grimmory.yml` разделяет device endpoints `/api/koreader/**` и `/api/v1/opds/**` в отдельный Caddy handler.
- Для этих endpoints upstream compression отключён и установлен `Accept-Encoding: identity`; Caddy не добавляет proxy Basic Auth и не изменяет `Authorization`, `X-Auth-*`, `Range`, `WWW-Authenticate` или download headers.
- Запросы с `Accept-Encoding: gzip, br` подтверждённо возвращают `401` без `Content-Encoding` для KOReader и OPDS. Caddy validate, Grimmory health и idempotent rerun успешны.
- Дополнительно исправлен Grimmory OPDS `500` из-за `No acceptable representation`: Caddy нормализует `Accept` только для Atom/OpenSearch catalog routes, оставляя original `Accept` для book download/cover routes.