# Контейнер 104 (Paperless): Paperless-ngx, PostgreSQL, Redis

Подробное описание LXC-контейнера **104** на Proxmox (192.168.1.104): архив документов Paperless-ngx (домен docs.katykhin.ru), PostgreSQL 18, Redis 8 для очередей задач.

---

## Общие сведения

- **Хостнейм:** paperless  
- **IP:** 192.168.1.104/24  
- **ОС:** Debian 12 (bookworm)  
- **Ресурсы:** 1 core, 2 GB RAM (из [архитектуры](../architecture/architecture.md))  
- **Доступ:** с Proxmox — `pct exec 104 -- bash` или по SSH на 192.168.1.104, если настроен.

Диск контейнера: ~10 GB, занято ~3.9 GB. Основной объём данных — в каталоге **/mnt/paperless-data/** (ZFS: `tank/subvol-104-disk-0`): данные приложения, медиа (документы), БД PostgreSQL. Плюс образы и тома Docker (~2 GB). Следить за местом и логами (см. раздел «Логи и ротация» и TODO).

---

## Доступ и логины

- **Debian (CT 104):** логин `root` (пароль — в менеджере паролей или как настраивал при установке).
- **Paperless (веб):** http://192.168.1.104:8000 (или через NPM: https://docs.katykhin.ru, если настроен). Учётные записи — пользователи Paperless (создаются в веб-интерфейсе).

---

## Сервисы (Docker Compose)

Один проект: **/opt/paperless/docker-compose.yml**. Сеть: **paperless_default** (bridge).

| Контейнер                | Образ                    | Порты (хост) | Назначение |
|--------------------------|--------------------------|--------------|------------|
| paperless-webserver-1    | paperless-ngx/paperless-ngx:latest | 8000         | Веб-интерфейс, API, OCR, фоновые задачи (Celery) |
| paperless-db-1           | postgres:18              | —            | БД Paperless |
| paperless-broker-1       | redis:8                  | —            | Очередь задач (Celery broker) |

---

## 1. Paperless-ngx (webserver)

**Каталог:** `/opt/paperless/`  
**Compose:** `docker-compose.yml`, переменные из **docker-compose.env** (не коммитить).

**Порты:** 8000 (хост) → 8000 (контейнер).  
**Тома:**
- `/mnt/paperless-data/data` → `/usr/src/paperless/data` (конфиг, индекс, логи, celerybeat-schedule, lock-файлы).
- `/mnt/paperless-data/media` → `/usr/src/paperless/media` (оригиналы и производные документов: `documents/`).
- `./export` → `/usr/src/paperless/export` (экспорт из приложения).
- `./consume` → `/usr/src/paperless/consume` (каталог для автоматического импорта: сюда класть файлы для постановки в очередь).

**Переменные окружения:** из `docker-compose.env`: PAPERLESS_URL, PAPERLESS_SECRET_KEY, PAPERLESS_TIME_ZONE, PAPERLESS_OCR_LANGUAGE(S). В compose заданы: PAPERLESS_REDIS=redis://broker:6379, PAPERLESS_DBHOST=db.

**Структура данных на хосте:**
- `/mnt/paperless-data/data/` — `index/` (поисковый индекс), `log/` (celery.log, paperless.log; приложение может создавать rotated файлы celery.log.1, .2 и т.д.), `celerybeat-schedule.db`, `.index_version`, `migration_lock`.
- `/mnt/paperless-data/media/documents/` — подкаталоги с оригинальными и обработанными файлами документов.

**Команды:**
```bash
cd /opt/paperless && docker compose up -d
docker logs paperless-webserver-1
docker exec paperless-webserver-1 document_exporter /usr/src/paperless/export --no-input  # экспорт
```

Импорт: положить файлы (PDF, изображения и т.д.) в `/opt/paperless/consume/` на хосте — Paperless подхватит их и обработает (OCR, теги, корреспонденты настраиваются в веб-интерфейсе).

---

## 2. PostgreSQL (db)

**Образ:** postgres:18.  
**Том:** `/mnt/paperless-data/pgdata` → `/var/lib/postgresql`.  
**Переменные:** POSTGRES_DB=paperless, POSTGRES_USER=paperless, POSTGRES_PASSWORD=paperless (в compose).  
Зависимость: webserver зависит от db и broker.

**Команды:**
```bash
docker exec paperless-db-1 pg_isready -U paperless
docker exec paperless-db-1 psql -U paperless -d paperless -c '\dt'
```

---

## 3. Redis (broker)

**Образ:** redis:8.  
**Том:** volume `redisdata` → `/data` (внутри контейнера). На хосте: `/var/lib/docker/volumes/paperless_redisdata/_data`.  
Используется как брокер для Celery (очередь задач OCR и др.).

**Команды:**
```bash
docker exec paperless-broker-1 redis-cli ping
docker logs paperless-broker-1
```

---

## Порты (сводка на хосте)

| Порт | Сервис / примечание |
|------|----------------------|
| 8000 | Paperless-ngx (веб)  |

---

## Логи и ротация

- **Базовая политика LXC:** в контейнере настроен logrotate `/etc/logrotate.d/homelab-lxc.conf` — 14 дней, 50 MB, 5 архивов (системные логи в `/var/log`). Подробнее: [Logrotate — базовая политика homelab](../maintenance/logrotate/README.md).
- **Paperless:** логи приложения в **/mnt/paperless-data/data/log/**:
  - `celery.log` — фоновые задачи (OCR, индекс и т.д.); приложение может делать собственную ротацию (celery.log.1, .2, .3). На момент проверки каталог ~568 KB.
  - `paperless.log` — основной лог приложения.
  Для этих файлов **нет правил logrotate** на хосте — при длительной работе объём может расти (см. TODO).
- **Docker:** драйвер логов контейнеров — **json-file** без ограничения размера и количества файлов. Рост логов контейнеров (stdout/stderr) может заполнять диск.

**Системный logrotate** в CT — только стандартные правила (apt, dpkg, btmp, wtmp). Отдельных правил для Paperless или Docker нет.

**Риск:** при большом количестве документов и активной очереди Celery логи в `data/log/` и логи Docker могут разрастаться. Рекомендуется настроить ротацию (см. TODO).

---

## Запуск и порядок поднятия

1. Убедиться, что смонтирован `/mnt/paperless-data` (ZFS или иной бэкенд).
2. `cd /opt/paperless && docker compose up -d`.  
   Порядок: broker и db поднимаются первыми, затем webserver (depends_on).

После смены переменных в `docker-compose.env` или compose: `docker compose up -d` (пересоздание при необходимости). Обновление образа: `docker compose pull && docker compose up -d`.

---

## Уязвимости и риски

1. **Пароли в конфигах:** В `docker-compose.yml` заданы пароль БД (paperless/paperless). В `docker-compose.env` — PAPERLESS_SECRET_KEY, PAPERLESS_URL и др. Файлы лежат только на сервере; не помещать в публичный репозиторий. Ограничить права на `docker-compose.env` (например chmod 600).
2. **Доступ по порту 8000:** Веб-интерфейс доступен по 192.168.1.104:8000 из LAN. Снаружи доступ только через NPM (https://docs.katykhin.ru). Не пробрасывать 8000 в интернет.
3. **Логи:** Ротация логов Paperless (`data/log/`) и Docker не настроена — возможен рост и заполнение диска (см. TODO).
4. **Каталог consume:** Файлы в `/opt/paperless/consume/` автоматически обрабатываются и удаляются после импорта. Не класть туда единственные копии важных файлов без бэкапа.

---

## TODO по контейнеру 104

- [x] **Базовая политика logrotate:** для системных логов настроена (homelab-lxc.conf — 14 дней, 50 MB, 5 архивов). См. [Logrotate — базовая политика homelab](../maintenance/logrotate/README.md).
- [ ] **Логи Paperless:** Настроить logrotate для `/mnt/paperless-data/data/log/*.log`: например еженедельная ротация или по размеру (max 50–100 MB), хранить 3–4 копии, сжатие. Создать `/etc/logrotate.d/paperless` и проверить работу.
- [ ] **Логи Docker:** Включить ограничение размера логов контейнеров: в `docker-compose.yml` добавить для сервисов `logging: driver: json-file options: max-size: "50m" max-file: "3"` или задать default в `/etc/docker/daemon.json` и перезапустить Docker, затем контейнеры.
- [ ] **Домен и NPM:** При необходимости настроить в NPM proxy для docs.katykhin.ru → 192.168.1.104:8000, выпустить SSL. В Paperless в `docker-compose.env` задать PAPERLESS_URL=https://docs.katykhin.ru (если ещё не задан).
- [ ] **Мониторинг диска:** Следить за местом на корне и на `/mnt/paperless-data` (df -h). При желании — оповещение при заполнении выше порога (например 80%).
- [ ] **Резервное копирование:** Регулярный бэкап критичных данных (оценка размеров на момент документации):
  - **`/mnt/paperless-data/data`** — конфиг, индекс, логи, celerybeat-schedule. ~1 MB (логи могут расти).
  - **`/mnt/paperless-data/media`** — все документы (оригиналы и производные). ~178 MB (будет расти с новыми документами).
  - **`/mnt/paperless-data/pgdata`** — БД PostgreSQL. ~22 MB. Для консистентного бэкапа предпочтительно дамп: `docker exec paperless-db-1 pg_dump -U paperless paperless > backup_paperless_$(date +%Y%m%d).sql`.
  - **`/var/lib/docker/volumes/paperless_redisdata`** — данные Redis. ~12 KB. Восстановление не критично (очередь задач), по желанию.
  - **`/opt/paperless`** — docker-compose.yml, docker-compose.env (секреты), каталоги consume/export. ~20 KB. Обязательно; docker-compose.env не коммитить.

  Учитывать, что `/mnt/paperless-data` может быть отдельным ZFS-томом (tank/subvol-104-disk-0) — при бэкапе с хоста Proxmox нужно включить этот каталог или снапшот ZFS.

---

## Связь с другими документами

- [Архитектура и подключение](../architecture/architecture.md) — таблица контейнеров, домен docs.katykhin.ru, схема сети.
- [Контейнер 100 (nginx)](container-100.md) — NPM, через который проксируется docs.katykhin.ru.
- [Paperless + Ollama: поиск по документам](paperless-ollama.md) — интеграция Paperless-ngx с Ollama для вопросов по документам.