Paperless‑ngx с Docker Compose — моят практически урок

Какво представлява Paperless‑ngx

• Самостоятелно хостван архив за документи с мощно търсене и OCR.
• Автоматично поглъщане на файлове от папка (consume) и e‑mail IMAP.
• Тагове, кореспонденти, правила и бърз export/import.
• Работи отлично в Docker и е удобен за Proxmox LXC/VM.

Предпоставки

• Инсталиран Docker и Docker Compose.
• Свободни портове (примерно 8778) и ~2 GB RAM минимум за комфортно OCR‑ване.
• Директории на хоста за данни/медия/експорт/consume.

Готов docker-compose.yml

docker-compose.yml

Копирайversion: "3.4"

version: "3.4"

services:
  broker:
    image: redis:7
    restart: unless-stopped

  db:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless
    volumes:
      - ./data/db:/var/lib/postgresql/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    depends_on:
      - db
      - broker
    ports:
      - "8778:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless
      PAPERLESS_SECRET_KEY: "paste_a_long_random_secret_here"
    restart: unless-stopped

Създаване на директории и стартиране

Копирайmkdir -p data/db media export consume
# Генерирай силен секрет (копирай изхода и го постави в compose файла)
openssl rand -base64 45

# Стартирай
docker compose up -d

# Гледай логовете (първи старт прави миграции и може да отнеме малко)
docker logs -f $(docker ps --format '{{.Names}}' | grep paperless-webserver)

Първоначална конфигурация

1. Отвори http://<IP>:8778.
2. Създай админ потребител:

   Копирайdocker exec -it $(docker ps --format '{{.Names}}' | grep paperless-webserver) \
     python3 manage.py createsuperuser

3. Настрой тагове, кореспонденти и правила в уеб интерфейса.

OCR на български и качество

Paperless използва Tesseract. За по‑добри резултати с кирилица:

• Добави PAPERLESS_OCR_LANGUAGE: "bul+eng" в environment.
• Ползвай по‑висока резолюция при сканиране (300 DPI+).
• За снимани документи — опитай да изправиш перспективата преди качване.

Интеграции

Backup стратегия

• Снапшоти в Proxmox преди ъпдейти.
• Периодичен rsync на ./data, ./media, ./export и ./data/db към NAS/облак.
• Експорт от UI за бърз off‑site архив.

Troubleshooting (често срещани)

Сигурност

• Силен PAPERLESS_SECRET_KEY и дълги пароли.
• HTTPS навсякъде, по възможност достъп само през VPN (WireGuard/Tailscale).
• Ограничени потребители/ролите в админ панела.

Заключение

Paperless‑ngx бързо се превърна в личния ми централен архив за документи — лек, бърз и удобен. Горният compose файл и насоките са напълно достатъчни, за да го вдигнеш за минути и да го интегрираш в домашната инфраструктура.