Как да инсталираме Paperless-ngx с Docker Compose на Ubuntu

Въведение

Управлението на документи в дигитална среда често се превръща в предизвикателство, особено когато броят на файловете (PDF, DOC, сканирани изображения) нараства. Paperless-ngx е модерна система за управление на документи (DMS), която предлага автоматично индексиране, OCR (разпознаване на текст) и мощна търсачка.

В тази статия ще разгледаме стъпка по стъпка как да инсталираме и конфигурираме Paperless-ngx с Docker Compose върху Ubuntu, така че да работи стабилно и надеждно.

---

Изисквания

Преди да започнем, уверете се, че имате:

• Ubuntu сървър (20.04+)
• Инсталиран Docker
• Инсталиран Docker Compose
• Достъп до терминал (SSH)

🐳

Ако все още нямате инсталиран Docker…

Инсталиране на Docker и Docker Compose на Debian 12

→

---

Стъпка 1: Подготовка на директориите

Създаваме структура за съхранение на данните:

mkdir -p /data/paperless/{data,media,export,consume,db}

Обяснение:

• data – метаданни
• media – реалните файлове
• export – експортирани документи
• consume – входяща папка за автоматичен импорт
• db – база данни

---

Стъпка 2: Създаване на docker-compose.yml

Създайте файл:

nano docker-compose.yml

И добавете следната конфигурация:

version: "3.8"

services:
  broker:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped
    command: redis-server --save "" --appendonly no

  db:
    image: postgres:15
    container_name: paperless-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless_password_change_me
    volumes:
      - /data/paperless/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless"]
      interval: 10s
      timeout: 5s
      retries: 5

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      broker:
        condition: service_started
    ports:
      - "8000:8000"
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless_password_change_me

      # Разкоментирайте, ако използвате домейн:
      # PAPERLESS_URL: https://paperless.yourdomain.com
      # PAPERLESS_CSRF_TRUSTED_ORIGINS: https://paperless.yourdomain.com

      PAPERLESS_SECRET_KEY: "change_me_to_something_long"
      USERMAP_UID: 1000
      USERMAP_GID: 1000

      PAPERLESS_OCR_LANGUAGE: bul+eng
      PAPERLESS_TIME_ZONE: Europe/Sofia
      PAPERLESS_OCR_LANGUAGES: bul # Помага за по-бързо разпознаване

      PAPERLESS_CONSUMER_POLLING: 60
      PAPERLESS_FILENAME_FORMAT: "{created_year}/{correspondent}/{title}"


    volumes:
      - /data/paperless/data:/usr/src/paperless/data
      - /data/paperless/media:/usr/src/paperless/media
      - /data/paperless/export:/usr/src/paperless/export
      - /data/paperless/consume:/usr/src/paperless/consume

---

Стъпка 3: Стартиране на контейнерите

Изпълнете:

docker compose up -d

След няколко секунди системата ще бъде достъпна на:

http://IP_НА_СЪРВЪРА:8000

---

Стъпка 4: Създаване на администраторски потребител

По подразбиране няма създаден потребител. Трябва ръчно да добавите такъв:

docker exec -it paperless python3 manage.py createsuperuser

Ще бъдете подканени да въведете:

• Username
• Email (по избор)
• Password

След това можете да се логнете в уеб интерфейса.

---

Стъпка 5: Работа с документи

Качване на файлове

Имате няколко варианта:

• Drag & Drop в браузъра
• Upload бутон
• Автоматично чрез папката:

/data/paperless/consume

Пример:

cp *.pdf /data/paperless/consume/

Всички файлове ще бъдат автоматично обработени.

---

Стъпка 6: ⚠️ Настройка при използване на домейн (ВАЖНО)

Ако ще използвате домейн (напр. през Cloudflare или nginx), трябва задължително да добавите следните променливи:

PAPERLESS_URL: https://tvoiat-domain.com
PAPERLESS_CSRF_TRUSTED_ORIGINS: https://tvoiat-domain.com

⚠️ Важно:

• НЕ добавяйте / накрая на URL-а
• Ако използвате www, добавете и двата домейна

Пример:

PAPERLESS_CSRF_TRUSTED_ORIGINS: https://tvoiat-domain.com,https://www.tvoiat-domain.com

Защо е необходимо това?

Без тези настройки ще получите грешка:

403 CSRF verification failed

Това е защитен механизъм на системата, който изисква домейнът да бъде изрично разрешен.

---

Често срещани проблеми

1. Не може да се логнете

• Проверете дали сте създали потребител
• Изчистете cache/cookies

2. OCR не работи

• Уверете се, че tika контейнерът работи
• Проверете езиковите настройки

3. Бавна обработка

• Нормално при първоначално индексиране
• OCR натоварва CPU

---

Добри практики

• Използвайте силни пароли
• Правете редовни backup-и:rsync -av /data/paperless /backup/
• Използвайте /consume за автоматизация
• Групирайте документи с тагове

---

Заключение и лична препоръка

След като преминете през всички стъпки по инсталацията и първоначалната настройка, ще разберете колко удобен може да бъде един добре организиран документен архив. Paperless-ngx не е просто място за съхранение на файлове – това е инструмент, който реално спестява време и усилия при търсене, сортиране и управление на информация.

От личен опит мога да препоръчам още в началото да изградите добра структура и навици на работа. Използвайте тагове, именувайте файловете смислено и най-вече – възползвайте се от папката /consume, която автоматизира целия процес по качване на документи. Това ще ви спести ръчна работа и ще направи системата много по-ефективна.

Ако планирате да използвате системата в дългосрочен план, силно препоръчително е:

• да настроите регулярни backup-и
• да използвате домейн с HTTPS достъп
• да ограничите достъпа до системата (особено ако е публично достъпна)

Не на последно място – не се притеснявайте да експериментирате. Paperless-ngx предлага доста възможности за автоматизация и оптимизация, които можете да настроите според вашите нужди.

С правилна конфигурация и малко първоначално усилие, ще получите надеждна, бърза и удобна система за управление на документи, която значително ще улесни ежедневната ви работа.