Paperless-ngx 2.20 pe un VPS: cum alegi corect OCR-ul, ingestia prin email și layout-ul de stocare din prima zi

Dacă vrei să instalezi Paperless-ngx pe un VPS, întrebarea reală nu este "pot să-l pornesc?". Asta este partea ușoară. Întrebarea reală este dacă îl vei instala într-un mod care încă are sens peste șase luni, când vei avea mii de PDF-uri, joburi OCR în coadă, reguli de ingestie prin email care s-au înmulțit și backupuri suficient de mari încât să te doară dacă ai gândit prost layout-ul de stocare. Paperless-ngx este genul de aplicație care răsplătește setup-ul corect al părților plictisitoare încă din prima zi.

Punctul de pornire corect în 2026 este simplu: rulezi Paperless-ngx 2.20.x, îl pui pe un LXC generos sau pe un KVM mic, folosești PostgreSQL, ții Redis local, separi clar directoarele pentru ingestie și arhivă și decizi de la început dacă vrei conversie pentru documente Office și ingestie prin email. Dacă sari peste aceste decizii și doar "arunci un Docker Compose" pe server, de obicei vei ajunge să refaci stack-ul mai târziu.

Acest tutorial nu este o prezentare vagă. Este traseul de instalare pentru un VPS Paperless-ngx gândit practic: OCR configurat corect, suport real pentru ingestie prin email, Docker Compose curat și un layout de stocare care nu devine o mizerie în momentul în care începi să imporți documente reale.

De ce merită să instalezi acum Paperless-ngx 2.20

Paperless-ngx era deja util și înainte de ramura 2.20, dar 2.20.x este un punct de plecare mai bun pentru instalări noi decât stack-urile vechi pe care oamenii le copiază încă din articole depășite. Changelog-ul oficial arată trei lucruri care contează operațional: versiunea 2.20.0 a mutat imaginea Docker pe Debian Trixie, a adus îmbunătățiri de performanță și startup, iar versiunile ulterioare 2.20.x au inclus remedieri de securitate. Asta este suficient ca să nu pornești o instalare nouă pe un branch mai vechi fără motiv.

Asta nu înseamnă că trebuie să urmărești orbește orice ultimă versiune. Înseamnă doar că nu are sens să începi un deployment nou pe un stack mai vechi dacă nu ai un motiv clar. Dacă instalezi aplicația astăzi pe un VPS, pornește de la o versiune 2.20.x actuală, notează exact ce tag ai folosit și actualizează ulterior controlat, nu din inerție sau din întâmplare.

LXC sau KVM: ce tip de VPS se potrivește de fapt pentru Paperless-ngx

Paperless-ngx rulează bine atât pe un LXC generos, cât și pe un VPS KVM mic. Alegerea corectă depinde mai puțin de aplicație și mai mult de câtă izolare vrei, cât de simplu este storage-ul și câtă răbdare ai pentru ciudățeniile care apar când începi să pui containere peste containere sau mount-uri neobișnuite.

Un LXC generos este de obicei alegerea mai bună când:

• vrei overhead mai mic
• storage-ul este local și simplu
• nu ai nevoie de izolare puternică de tip VM
• ești confortabil cu Docker într-un mediu containerizat

Un KVM mic este de obicei alegerea mai bună când:

• vrei o graniță de izolare mai curată
• te aștepți să adaugi reverse proxy, backup agents sau alte servicii în jurul lui
• nu vrei surprize legate de nesting și mount-uri
• preferi mai puține cazuri-limită la nivel de storage și permisiuni

Pe scurt, dacă este arhiva ta personală de documente și îți cunoști bine mediul Proxmox sau VPS-ul, un LXC bine dimensionat este o alegere complet rezonabilă. Dacă aplicația este importantă pentru business, folosită de mai mulți utilizatori sau știi deja că nu vrei să pierzi timp cu debugging de container nesting și mount behavior, alege un KVM mic și închide subiectul.

Pentru majoritatea instalărilor mici, un punct de pornire sănătos arată așa:

• 2 vCPU
• minimum 4 GB RAM
• 6 până la 8 GB RAM dacă te aștepți la OCR mai greu și conversii mai dese
• 60 până la 100 GB SSD la început, mai mult dacă ai deja un backlog serios de PDF-uri scanate

Dacă ai nevoie de un loc curat unde să-l rulezi, acesta este exact genul de workload care se potrivește bine pe Servere Virtuale ServerSpan. Dacă vrei aplicația, dar nu și administrarea Linux din jurul ei, aici Administrarea Linux începe să fie mai rațională decât promisiunea că "rezolvi tu mai târziu".

Layout-ul de stocare care te scutește de dureri mai târziu

Aici greșesc multe tutoriale grăbite. Paperless-ngx nu are nevoie doar de "un volum". Are nevoie de directoare care rămân ușor de înțeles și de administrat după ce instanța începe să crească.

Cel mai bine este să gândești în cinci zone funcționale separate:

• consume pentru fișierele noi care urmează să fie procesate
• media pentru documentele arhivate și thumbnail-urile lor
• data pentru date interne ale aplicației, index, modele și alte stări persistente
• export pentru exporturile explicite
• db pentru datele PostgreSQL

Nu îngrămădi totul într-un singur folder vag dacă îți pasă de backupuri, depanare sau migrare. Da, aplicația poate funcționa tehnic și cu un layout mai simplu. Asta nu înseamnă că este o idee bună.

Un layout curat pe host poate arăta așa:

/srv/paperless/
├── consume/
├── media/
├── data/
├── export/
├── db/
└── compose/

Avantajul real este că poți trata backupurile diferit pentru media față de PostgreSQL, poți inspecta ușor ce intră în ingestie și poți muta tot stack-ul mai târziu fără să îți descurci singur improvizațiile.

Mai este o regulă importantă: ține consume pe storage local rapid, dacă poți. Dacă mai târziu alegi să arunci fișiere acolo dintr-un storage de rețea și observi că inotify nu se comportă cum trebuie, Paperless documentează fallback-ul PAPERLESS_CONSUMER_POLLING. Dar asta este o soluție de ocolire, nu punctul ideal de pornire.

Ce fac de fapt OCR-ul, Tika și Gotenberg

Mulți folosesc termenul OCR prea larg în contextul acesta. Pipeline-ul Paperless-ngx nu este o singură funcție compactă.

• OCR-ul transformă conținutul scanat în text căutabil.
• Tika ajută la parsarea conținutului și metadatelor pentru tipuri de documente care nu sunt simple PDF-uri.
• Gotenberg se ocupă de conversia documentelor Office către formate ușor de procesat.
• Tika și Gotenberg împreună sunt necesare dacă vrei parsare corectă pentru fișiere .eml și pentru atașamente Office.

De aceea trebuie să decizi devreme dacă instanța ta va arhiva doar PDF-uri scanate și imagini sau dacă vrei și documente Office și ingestie prin email. Dacă sari peste Tika și Gotenberg acum, iar peste două luni vrei să procesezi emailuri și fișiere Office corect, vei ajunge să revizuiești din nou tot stack-ul Compose.

Răspunsul practic pentru o instalare nouă este simplu: include Tika și Gotenberg din prima zi, cu excepția cazului în care știi sigur că instanța va rămâne strict PDF-only.

Sistemul de bază și pachetele pregătitoare

Acest ghid presupune un VPS actual cu Debian 12 sau Ubuntu 24.04 și acces root. Începe prin a actualiza sistemul și a instala Docker plus pluginul Compose cum trebuie. Nu construi un stack nou de aplicații pe o bază deja depășită.

apt update
apt upgrade -y
apt install -y ca-certificates curl gnupg lsb-release

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker
docker version
docker compose version

Dacă rulezi pe Ubuntu, folosește repo-ul Docker pentru Ubuntu, nu copia orbește instrucțiunile pentru Debian. Ideea nu este linia exactă de repo. Ideea este să instalezi Docker curat și să-l verifici înainte ca aplicația să intre în discuție.

Creează structura de directoare pentru Paperless-ngx

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

Folosește o locație clară, de tipul /srv/paperless sau altă cale dedicată pentru servicii. Nu împrăștia volumele prin directoare personale și alte locuri aleatorii, dacă nu vrei să uiți singur unde ți-ai pus datele.

Stack-ul Docker Compose care chiar are sens

Pentru o instalare nouă, folosește PostgreSQL. Documentația oficială Paperless-ngx recomandă PostgreSQL pentru instalări noi. Asta este suficient cât să nu începi o instanță proaspătă pe SQLite doar pentru că ai găsit un fișier de exemplu mai scurt undeva pe internet.

Creează fișierul docker-compose.yml astfel:

services:
  broker:
    image: docker.io/library/redis:7
    container_name: paperless-redis
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:16
    container_name: paperless-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: schimba-parola-acum
    volumes:
      - /srv/paperless/db:/var/lib/postgresql/data

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8
    container_name: paperless-gotenberg
    restart: unless-stopped
    command:
      - gotenberg
      - --chromium-disable-javascript=true
      - --chromium-allow-list=file:///tmp/.*

  tika:
    image: docker.io/apache/tika:latest
    container_name: paperless-tika
    restart: unless-stopped

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.8
    container_name: paperless-web
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: schimba-parola-acum
      PAPERLESS_URL: https://paperless.example.com
      PAPERLESS_SECRET_KEY: schimba-asta-cu-un-secret-lung-si-aleator
      PAPERLESS_TIME_ZONE: Europe/Bucharest
      PAPERLESS_OCR_LANGUAGE: eng+ron
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_CONSUMER_POLLING: 0
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: schimba-parola-acum
    volumes:
      - /srv/paperless/data:/usr/src/paperless/data
      - /srv/paperless/media:/usr/src/paperless/media
      - /srv/paperless/export:/usr/src/paperless/export
      - /srv/paperless/consume:/usr/src/paperless/consume

volumes:
  redisdata:

Acesta nu este singurul stack valid. Este însă unul care pune bine lucrurile importante încă din prima zi:

• PostgreSQL este separat și persistent.
• Redis este local și nu este împărțit cu alte aplicații fără legătură.
• Tika și Gotenberg sunt incluse de la început.
• Căile de date Paperless sunt explicite și bind-mounted.
• Imaginea este fixată pe o versiune 2.20.x, nu pe latest.

Schimbă imediat parolele și cheia secretă. Valorile din exemplu sunt placeholders, nu recomandări.

Pornește stack-ul și verifică-l corect

cd /srv/paperless/compose
docker compose up -d
docker compose ps
docker compose logs -f webserver

Nu te opri la "containerele sunt up". Așteaptă până când aplicația răspunde și logurile arată startup normal. Abia apoi verifici UI-ul local:

curl -I http://127.0.0.1:8000

Dacă urmează să o expui prin reverse proxy, asta vine după. Nu îndrepta DNS-ul către aplicație până nu știi sigur că instanța locală este sănătoasă.

Reverse proxy și URL public configurate corect

Dacă nu este un deployment strict privat, pune Paperless în spatele unui reverse proxy și folosește un hostname real. Variabila care contează cel mai mult aici este PAPERLESS_URL. Ea trebuie să corespundă exact schemei și hostname-ului public pe care îl vei folosi în realitate.

De exemplu:

PAPERLESS_URL=https://paperless.example.com

Nu o lăsa ambiguă sau greșită. Documentația Paperless arată clar că această setare influențează comportamentul legat de host și CSRF. Dacă pui aplicația în spatele unui proxy mai târziu și uiți să actualizezi variabila, îți creezi singur probleme administrative care nu aveau niciun motiv să existe.

OCR-ul corect din prima zi

Decizia legată de OCR nu este doar "activez sau nu activez OCR?". Întrebarea reală este ce limbi ai nevoie să recunoască și dacă sistemul va produce text căutabil suficient de bun pentru documentele tale.

Dacă arhiva ta este predominant în română și engleză, un punct de pornire sănătos este:

PAPERLESS_OCR_LANGUAGE=eng+ron

Dacă lași doar engleză, iar jumătate din documente sunt în română, OCR-ul tot va rula. Doar că rezultatul va fi mai slab decât trebuie. Asta contează mult mai târziu, când vrei să găsești rapid facturi, contracte, acte sau documente scanate prost și te bazezi pe funcția de căutare.

Mai este ceva important: OCR-ul nu repară miraculos documente scanate prost. Dacă inputul este prost, rezultatul va rămâne limitat:

• scanări de calitate slabă
• contrast prost
• pagini înclinate
• fotografii de documente care nu au fost scanate corect

Paperless este foarte util. Nu este magie. Dacă documentul de intrare este prost, textul extras va avea limite reale.

Ingestia prin email, configurată corect de la început

Aici aplicația devine cu adevărat valoroasă. Dacă facturile, extrasele, contractele sau notificările ajung prin email, nu vrei să le redirecționezi manual la nesfârșit. Folosește corect mecanismul de ingestie încorporat.

Fluxul oficial este simplu în interfață:

• definești unul sau mai multe conturi de email
• creezi reguli de prelucrare pentru acele conturi
• decizi cum tratezi atașamentele, conținutul și rutarea documentelor

Partea operațională importantă este să stabilești politica corect încă de la început:

• folosește, dacă poți, o căsuță dedicată pentru facturi și documente administrative
• nu conecta Paperless la un inbox personal zgomotos și plin de junk
• etichetează coerent documentele venite pe email
• folosește deliberate correspondents, tags și reguli, nu ad-hoc

Dacă vrei ca Paperless să proceseze bine emailuri și documente Office, exact de aceea Tika și Gotenberg au fost incluse mai sus. Acesta este unul dintre acele lucruri enervante de retrofit dacă le-ai sărit la instalare.

Modelul de stocare care păstrează arhiva utilizabilă

Paperless-ngx poate stoca documente și fără o structură specială de fișiere. Asta este acceptabil pentru un laborator. Este slab pentru o arhivă reală. Decide devreme dacă vrei o organizare pe disc care să aibă logică și în afara interfeței web.

Un punct de pornire sănătos este să păstrezi arhiva grupată, la nevoie, după corespondent și an, astfel încât exporturile și backupurile să aibă o logică umană și în afara UI-ului. Poți folosi formatările de nume și căi din Paperless mai târziu, dar nu complica inutil asta în prima zi. Important este ca media să fie un director durabil, separat de consume și inclus clar în planul de backup.

Nu pune arhiva pe storage remote fragil doar pentru că poți. Dacă VPS-ul are SSD local rapid, începe de acolo. Treci la un design mai complex doar când înțelegi cu adevărat compromisurile pentru backup și restore.

Permisiuni și ownership: partea pe care mulți o strică în tăcere

Paperless este foarte ușor de stricat dacă tratezi neglijent permisiunile volumelor. Documentația este clară: directoarele folosite de aplicație trebuie să existe și să fie scriibile de utilizatorul cu care rulează serviciul. În deployment-urile pe Docker, asta devine responsabilitate pe host.

Dacă ingestia nu merge, documentele nu sunt preluate sau fișierele rămân blocate în folderul de intrare, permisiunile sunt printre primele lucruri pe care trebuie să le verifici.

ls -lah /srv/paperless
ls -lah /srv/paperless/consume
ls -lah /srv/paperless/media
docker compose logs -f webserver
docker compose logs -f gotenberg
docker compose logs -f tika

Nu aștepta să imporți 800 de documente ca să descoperi că un director a fost montat greșit și că aplicația a funcționat doar pe jumătate de la început.

Backup-ul trebuie gândit din prima zi

Dacă arhiva contează, strategia de backup este parte din instalare, nu ceva ce "rezolvi mai târziu când ai timp". În Paperless există două zone care contează decisiv:

• baza de date
• fișierele media ale documentelor

Dacă pierzi oricare dintre ele, restore-ul devine urât. Regula de bază este simplă:

• fă backup regulat la PostgreSQL
• fă backup la /srv/paperless/media
• fă backup și la /srv/paperless/data
• testează mecanismul de restore înainte să ai încredere deplină în sistem

Dacă este vorba despre documente de business, nu te minți cu ideea că "furnizorul VPS are snapshots". Asta nu este strategie serioasă de retenție pentru documente.

Ce merge de obicei prost la primele instalări Paperless

• oamenii pornesc o instalare nouă pe SQLite, deși PostgreSQL este recomandat
• sară peste Tika și Gotenberg, apoi se miră că documentele Office și emailurile sunt procesate slab
• îngrămădesc toate volumele într-un singur folder vag și regretă asta la backup sau migrare
• folosesc parole slabe sau lasă secret key-ul nemodificat
• nu se gândesc la limbile pentru OCR până când funcția de căutare dezamăgește
• expun aplicația public înainte ca stack-ul local să fie cu adevărat stabil

Niciuna dintre aceste probleme nu este deosebit de sofisticată. Sunt, pur și simplu, eșecuri de planificare. Tocmai de aceea se repetă atât de des.

Când este suficient un LXC generos și când un KVM mic este alegerea mai bună

Un LXC generos este suficient când instalarea este curată, storage-ul este local și vrei overhead redus pentru o arhivă self-hosted de documente. Un KVM mic este alegerea mai bună când îți pasă mai mult de izolare, de un comportament mai curat al Docker-ului și de o platformă pe care vrei să adaugi reverse proxy, monitorizare, backup agents și schimbări controlate.

Nu transforma alegerea asta într-o paralizie inutilă. Paperless-ngx nu este greu de găzduit. Doar pedepsește un layout grăbit de filesystem și servicii odată ce începi să te bazezi serios pe el.

Dacă vrei un loc curat unde să-l rulezi fără improvizații la infrastructură, folosește Serverele Virtuale ServerSpan. Dacă vrei aplicația, dar nu și toată partea de Linux din jurul Docker-ului, reverse proxy-ului, backupurilor și hardening-ului, mergi pe Administrare Linux ServerSpan și încetează să te prefaci că vei fi încântat să citești loguri de containere la 11 noaptea.

Concluzia practică

Instalarea corectă a Paperless-ngx pe un VPS nu este cea care doar pornește. Este cea care are limbile OCR potrivite, serviciile opționale deja puse la punct pentru emailuri și documente Office, un layout de stocare care încă are logică după ce arhiva crește, PostgreSQL din prima zi și un tip de VPS ales după izolarea și controlul de care ai cu adevărat nevoie.

Dacă îl construiești așa de acum, eviți majoritatea motivelor pentru care astfel de deployment-uri ajung refăcute mai târziu. Dacă îl construiești neglijent, Paperless-ngx tot va rula. Doar că va deveni încă o aplicație pe care "o pui la punct cum trebuie mai târziu".