Paperless-ngx Nedir ve Dijital Belge Arşivi Kurulumu

Faturalar, banka ekstreleri, sözleşmeler, garanti belgeleri, vergi kağıtları... Çoğumuzun evinde ya da ofisinde yıllar içinde birikmiş, dolapları dolduran ama aradığınızda asla bulamadığınız bir kağıt yığını vardır. "2022 yılına ait o elektrik faturası neredeydi?" sorusu, çekmeceleri karıştırmakla geçen yarım saatlik bir arayışa dönüşür. Dijitalleştirme çabaları da çoğu zaman işe yaramaz; belgeleri tarayıp bir klasöre tarama_001.pdf, tarama_002.pdf diye atarsınız ve sonuçta kağıt yığınının yerini, içinde ne olduğunu bilmediğiniz bir dosya yığını alır. Sorun ortadan kalkmaz, sadece ekrana taşınır.

Paperless-ngx tam olarak bu kaosu çözmek için tasarlanmış, açık kaynaklı ve kendi sunucunuzda barındırabileceğiniz (self-hosted) bir belge yönetim sistemidir. Belgelerinizi yalnızca saklamakla kalmaz; her PDF ve taranmış görselin içindeki metni OCR ile okur, otomatik olarak etiketler, kimden geldiğini ve hangi türde olduğunu tespit eder ve hepsini tek bir kutucuktan saniyeler içinde aranabilir hale getirir. Bu rehberde Paperless-ngx'in nasıl çalıştığını, Docker Compose ile nasıl kurulacağını, belgeleri otomatik işleyen tüketim klasörünü, akıllı etiketleme kurallarını ve arama gücünü kıdemli bir sistem yöneticisi gözünden, uçtan uca anlatacağız.

Paperless-ngx Nedir ve Hangi Sorunu Çözer#

Paperless-ngx, adından da anlaşılacağı gibi "kağıtsız" (paperless) bir ofis hayali üzerine kurulu bir projedir. Aslen "paperless" ve ardından "paperless-ng" olarak başlayan projelerin, orijinal geliştiricilerinin ayrılmasının ardından topluluk tarafından devralınıp yaşatılan halidir; sondaki "ngx" harfleri "next generation" anlamına gelir ve bugün en aktif geliştirilen, en olgun sürümdür. Bir belge arşivi olmasının ötesinde, tarayıcınızdan ya da e-postanızdan gelen her belgeyi otomatik işleyen küçük bir asistan gibi düşünülebilir.

Sistemin temel felsefesi basittir: bir belgeyi sisteme bir kez atarsınız, gerisini o halleder. Klasör hiyerarşisiyle uğraşmazsınız çünkü Paperless-ngx dosyaları klasörlere göre değil, üç temel metaveriye göre organize eder: etiketler (tags), yazışma türü (correspondent, yani belgenin kimden geldiği) ve belge türü (document type). Aynı fatura hem "elektrik", hem "2024", hem "ödendi" etiketini taşıyabilir; klasör mantığında bir dosyayı yalnızca tek bir yere koyabilirken burada aynı belge onlarca farklı bakış açısıyla filtrelenebilir. Aşağıdaki tablo, klasik dosya saklama ile Paperless-ngx yaklaşımının farkını özetliyor.

Paperless-ngx özellikle serbest çalışanlar, küçük işletmeler, muhasebe ile ilgilenen herkes ve kişisel arşivini düzene sokmak isteyen kullanıcılar için idealdir. Türkiye'de e-fatura, e-arşiv ve resmi yazışmaların PDF olarak birikmesi düşünüldüğünde, bunları tek bir aranabilir arşivde toplamak ciddi bir zaman kazancı sağlar.

Nasıl Çalışır: Belge İşleme Boru Hattı ve OCR#

Bir belge Paperless-ngx'e girdiğinde, arkada gözünüzden uzak bir işlem zinciri (pipeline) çalışır. Bu süreci anlamak, sistemin neden bu kadar güçlü olduğunu kavramak için önemlidir. Öncelikle belge sisteme alınır; ardından OCR (Optical Character Recognition, optik karakter tanıma) devreye girer. OCR, taranmış bir kağıdın ya da resim tabanlı bir PDF'in üzerindeki görselleri gerçek, seçilebilir ve aranabilir metne çevirir. Paperless-ngx bunun için arka planda güçlü ve olgun bir araç olan OCRmyPDF (ve dolayısıyla Tesseract motoru) kullanır.

OCR sonrası çıkarılan metin, veritabanında belgeyle ilişkilendirilir ve tam metin arama indeksine eklenir. İşte bu yüzden bir belgenin içindeki tek bir kelimeyi bile arayabilirsiniz. Bunun ardından sınıflandırma aşaması gelir: Paperless-ngx, belgenin metnine bakarak hangi etiketlerin, hangi gönderenin ve hangi türün uygun olduğunu tahmin eder. İlk kurulumda bu tahminler zayıftır, ancak siz belgeleri elle etiketledikçe sistem bir makine öğrenmesi sınıflandırıcısı eğiterek zamanla giderek isabetli hale gelir. Türkçe belgeler için OCR dilini tur olarak ayarlamak kritik önemdedir; aksi halde "ş", "ğ", "ı" gibi karakterler yanlış tanınır.

İşlem hattının son adımı arşivlemedir. Paperless-ngx her belge için iki kopya tutar: bir tanesi orijinal dosyanız (dokunulmadan saklanır), diğeri ise metin katmanı gömülmüş arşiv PDF'i. Yani orijinal taramanız salt görselse bile, arşiv kopyasının içinden metni kopyalayabilir ve içinde arama yapabilirsiniz. Bu ikili saklama, hem yasal geçerlilik (orijinali bozulmaz) hem de kullanışlılık açısından çok değerlidir.

Docker Compose ile Kurulum#

Paperless-ngx birden fazla bileşenden oluşur: web uygulaması, arka plan görevlerini işleyen bir worker, bir veritabanı (PostgreSQL önerilir), bir Redis kuyruğu ve OCR için Gotenberg ile Tika gibi yardımcı servisler. Bunları elle kurmak yorucu olacağından, en temiz yol Docker Compose kullanmaktır. Docker ve Docker Compose yüklü bir sunucuda (bir VDS sunucu ya da güçlü bir sanal sunucu bu iş için gayet yeterlidir) aşağıdaki adımları izleyebilirsiniz.

Önce proje için bir dizin oluşturup içine girin:

mkdir -p /opt/paperless && cd /opt/paperless
mkdir -p data media export consume pgdata redisdata

Ardından bir docker-compose.yml dosyası hazırlayın. Aşağıdaki yapılandırma PostgreSQL, Redis ve Paperless bileşenlerini bir arada ayağa kaldırır:

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

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: guclu-bir-parola-girin

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env

Yapılandırmanın kalanını docker-compose.env adında ayrı bir dosyaya koymak en temiz yöntemdir. Türkçe OCR ve temel ayarlar için bu dosya şöyle görünmeli:

PAPERLESS_REDIS=redis://broker:6379
PAPERLESS_DBHOST=db
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=guclu-bir-parola-girin
PAPERLESS_OCR_LANGUAGE=tur+eng
PAPERLESS_TIME_ZONE=Europe/Istanbul
PAPERLESS_URL=https://belge.ornekfirma.com
PAPERLESS_SECRET_KEY=uzun-rastgele-bir-anahtar-uretin
PAPERLESS_CONSUMER_POLLING=0
PAPERLESS_OCR_MODE=skip

PAPERLESS_OCR_LANGUAGE değerini tur+eng yapmak hem Türkçe hem de İngilizce belgeleri doğru tanımasını sağlar. Şimdi servisleri başlatın ve ilk yönetici kullanıcısını oluşturun:

docker compose up -d
docker compose run --rm webserver createsuperuser

Birkaç dakika içinde tüm imajlar indirilip servisler ayağa kalkacaktır. Artık tarayıcınızdan http://sunucu-ip:8000 adresine giderek oluşturduğunuz yönetici hesabıyla giriş yapabilirsiniz. Eğer birden fazla konteyneri görsel bir arayüzden yönetmeyi tercih ederseniz, Portainer ile bu yığını web üzerinden başlatıp durdurmak oldukça pratiktir.

Ters Vekil Sunucu ve HTTPS ile Yayınlama#

Paperless-ngx'i yalnızca yerel ağınızda kullanacaksanız 8000 portu yeterlidir, ancak internete açacaksanız kesinlikle bir ters vekil sunucu (reverse proxy) arkasına koyup HTTPS ile şifrelemelisiniz. Belgeleriniz kimlik, vergi ve mali bilgiler içerdiğinden, trafiğin şifresiz gitmesi kabul edilemez. Nginx ile örnek bir yapılandırma şöyledir:

server {
    listen 443 ssl;
    server_name belge.ornekfirma.com;

    ssl_certificate     /etc/letsencrypt/live/belge.ornekfirma.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/belge.ornekfirma.com/privkey.pem;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

Buradaki client_max_body_size 100M satırı önemlidir; büyük taramaların yüklenebilmesi için varsayılan sınırı yükseltir. Alan adınızın bu sunucuya bakması için basit bir A kaydı yeterlidir:

belge    IN    A    203.0.113.45

SSL sertifikasını Let's Encrypt ile ücretsiz alabilir ya da yönetimini kolaylaştırmak için hazır bir SSL sertifikası tercih edebilirsiniz. İnternete açık her servis gibi Paperless-ngx'i de kötü niyetli trafikten korumak isterseniz, önüne bir WAF veya DDoS koruması katmanı eklemek makul bir güvenlik yatırımıdır. Alan adınız yoksa bir alan adı kaydıyla başlayabilirsiniz.

Tüketim Klasörü ile Belgeleri Otomatik İçeri Alma#

Paperless-ngx'in en sevilen özelliği "consume" yani tüketim klasörüdür. Bu, sistemin sürekli izlediği özel bir dizindir; içine bir dosya bıraktığınız anda otomatik olarak alınır, OCR'dan geçirilir, sınıflandırılır ve arşivlenir. docker-compose.yml dosyasında bu klasörü ./consume olarak eşlemiştik. Belge eklemenin en basit yolu, dosyayı bu klasöre kopyalamaktır:

cp ~/Indirilenler/elektrik-faturasi-mart.pdf /opt/paperless/consume/

Birkaç saniye içinde belge kaybolur (işlendiği için) ve web arayüzünde işlenmiş haliyle belirir. Bu mekanizma özellikle tarayıcılarla harika çalışır: çoğu ağ tarayıcısını (network scanner) veya çok fonksiyonlu yazıcıyı, taradığı belgeleri doğrudan bu klasöre bir SMB paylaşımı üzerinden atacak şekilde ayarlayabilirsiniz. Böylece kağıdı tarayıcıya koyup butona basmanız yeterli olur; belge dijital arşivinize kendiliğinden düşer.

Tüketim klasörünü daha da akıllı hale getirebilirsiniz. Klasör içinde alt dizinler oluşturup Paperless-ngx'i bu dizin adlarını otomatik etikete çevirecek şekilde ayarlayabilirsiniz. Örneğin consume/muhasebe/ içine attığınız her belge otomatik olarak "muhasebe" etiketi alabilir. Bunun için env dosyanıza şu ayarı ekleyin:

PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true

Eğer belgelerinizi bir bulut depolamada ya da başka bir sunucuda tutuyorsanız, o kaynağı tüketim klasörüne bağlamak da mümkündür. Örneğin Nextcloud üzerinde belgelerinizi topluyorsanız, ilgili Nextcloud dizinini Paperless'ın consume klasörüyle senkronize ederek iki sistemi birbirini besleyecek şekilde çalıştırabilirsiniz. Ayrıca Paperless-ngx'in dahili e-posta getirme (mail fetching) özelliğiyle, belirli bir posta kutusuna gelen faturaları da otomatik olarak arşive çekebilirsiniz.

Etiketler, Yazışma Türleri ve Otomatik Eşleşme Kuralları#

Paperless-ngx'i sıradan bir dosya deposundan ayıran asıl güç, kural tabanlı otomatik sınıflandırmasıdır. Sistem her belgenin OCR ile çıkarılan metnini tarar ve tanımladığınız kurallara uyanları otomatik olarak etiketler. Yönetim panelinden bir etiket ya da yazışma türü oluştururken, ona bir "eşleşme algoritması" (matching algorithm) atarsınız. Bu algoritmalar belgeyle nasıl eşleşeceğini belirler:

Pratikte en çok kullanılan yöntem "Any" ve "Auto" karışımıdır. Örneğin "Elektrik" etiketi için eşleşme türünü "Any" seçip anahtar kelimelere "elektrik, kwh, sayaç, edaş, cezaevi caddesi" gibi belgede geçebilecek terimleri girersiniz. Bundan sonra içinde bu kelimelerden biri geçen her fatura otomatik olarak "Elektrik" etiketiyle işaretlenir. Gönderen (correspondent) için de aynı mantık geçerlidir: "Türk Telekom" adında bir yazışma türü oluşturup "türk telekom, ttnet" kelimelerini verdiğinizde, o firmadan gelen her belge doğru gönderene bağlanır.

"Auto" modu ise en zarif çözümdür ama sabır ister. Bu modda hiçbir anahtar kelime girmezsiniz; bunun yerine birkaç belgeyi elle doğru etiketlersiniz. Paperless-ngx bu örneklerden bir sınıflandırıcı model eğitir ve benzer belgeleri kendiliğinden tanımaya başlar. On beş yirmi belge elle etiketlendikten sonra sistemin isabet oranı gözle görülür şekilde artar. Deneyimlerime göre en verimli strateji, sık gelen ve deseni belli belgeler (elektrik, su, telefon faturaları) için "Any" kuralları yazmak, düzensiz ve çeşitli belgeler için ise "Auto" modunu tercih edip zamanla eğitmektir.

Güçlü Arama ile Belge Bulma#

Tüm bu düzenlemenin nihai amacı tek şey: aradığınızı saniyeler içinde bulmak. Paperless-ngx'in arama motoru, belgenin metadatasını (etiket, gönderen, tarih) ve OCR ile çıkarılmış tam metnini birlikte indeksler. Arayüzün üstündeki arama kutusuna bir kelime yazdığınızda, o kelimenin içinde geçtiği her belge anında listelenir. Bu, "faturanın dosya adını hatırlamak" gibi bir yükü tamamen ortadan kaldırır.

Arama, basit kelime aramasının çok ötesine geçer. Belirli operatörlerle çok hassas sorgular kurabilirsiniz. Örneğin sadece belirli bir etikete sahip ve belirli bir gönderenden gelen belgeleri süzmek için şu şekilde arayabilirsiniz:

tag:elektrik correspondent:"CK Boğaziçi" created:2024

Bu sorgu, 2024 yılında CK Boğaziçi'nden gelen ve "elektrik" etiketi taşıyan tüm belgeleri getirir. Metin içinde geçen belirli bir tutarı ya da sözleşme numarasını aramak da aynı kolaylıktadır; içeriğin tamamı indekslendiği için belgenin köşesinde kalmış küçük bir referans numarasını dahi bulabilirsiniz. Ayrıca yaklaşık eşleşme (fuzzy search) sayesinde OCR'ın küçük yazım hatalarına rağmen doğru sonuçlar dönebilir.

Kayıtlı görünümler (saved views) ise arayüzü kişiselleştirmenin en iyi yoludur. Sık kullandığınız filtreleri (örneğin "Bu ay vadesi gelen ödenmemiş faturalar") kaydedip ana panele sabitleyebilirsiniz. Böylece Paperless-ngx yalnızca bir arşiv değil, aktif bir iş takip aracına dönüşür.

Yedekleme, Güvenlik ve Bakım#

Belge arşiviniz artık işletmenizin hafızası haline geldiğine göre, onu korumak birinci önceliktir. Paperless-ngx'in en güzel yanlarından biri, taşınabilir bir dışa aktarma (export) mekanizması sunmasıdır. document_exporter komutu, tüm belgeleri, metadatayı ve ayarları veritabanından bağımsız, düz dosyalar halinde dışa aktarır:

docker compose exec webserver document_exporter ../export

Bu komut export klasörüne belgelerinizin okunabilir kopyalarını ve bir manifest.json dosyası bırakır. Bu klasörü düzenli olarak sunucu dışına, tercihen ayrı bir konuma yedeklemelisiniz. Otomatik ve güvenli bir çözüm için harici bir yedekleme hizmetiyle bu dizini gecelik olarak dış depolamaya aktarmak akıllıca olur. Alternatif olarak PostgreSQL veritabanının kendisini de yedekleyebilirsiniz:

-- Konteyner içinden veritabanı yedeği
pg_dump -U paperless paperless > /yedek/paperless-$(date +%F).sql

Güvenlik tarafında birkaç temel kural vardır. Öncelikle güçlü bir yönetici parolası kullanın ve mümkünse Paperless-ngx'i doğrudan internete değil, bir VPN ya da en azından ters vekil arkasında yayınlayın. Sistemin sürüm güncellemelerini takip etmek de önemlidir; docker compose pull ile yeni imajları çekip docker compose up -d ile yeniden başlatmak güncellemeyi tamamlar, ancak bunu her zaman güncel bir yedek aldıktan sonra yapın. Sunucunun bakımını kendiniz üstlenmek istemiyorsanız, sunucu yönetimi hizmetiyle güncellemeleri ve yedekleri profesyonel ellere bırakabilirsiniz. Bu tür self-hosted uygulamaları hızlıca denemek isteyenler için App Center üzerinden tek tıkla kurulabilen paketler de zamandan tasarruf sağlar.

Sıkça Sorulan Sorular#

Paperless-ngx ücretsiz mi?#

Evet, Paperless-ngx tamamen ücretsiz ve açık kaynaklıdır; GPL lisansıyla dağıtılır ve herhangi bir abonelik ya da lisans ücreti yoktur. Tek maliyetiniz, onu barındıracağınız sunucudur. Kişisel kullanımda evdeki küçük bir cihaz bile yeterken, birden fazla kullanıcının belge yüklediği bir işletme için bir sanal ya da VDS sunucu daha istikrarlı bir deneyim sunar. Yani yazılım bedava, ihtiyacınız olan tek şey onu çalıştıracak bir barındırma ortamıdır.

Türkçe belgelerde OCR düzgün çalışır mı?#

Kesinlikle çalışır, ancak doğru dil paketini seçmeniz şarttır. Yapılandırma dosyasında PAPERLESS_OCR_LANGUAGE değerini tur ya da hem Türkçe hem İngilizce belgeler için tur+eng olarak ayarladığınızda, Tesseract motoru Türkçe karakterleri ("ç", "ş", "ğ", "ı", "ö", "ü") yüksek doğrulukla tanır. Tarama kalitesi de sonucu doğrudan etkiler; 300 DPI ve üzeri, düz taranmış belgeler en iyi OCR sonucunu verir. Buruşuk ya da eğik taramalarda tanıma oranı doğal olarak düşer.

Resim tabanlı taranmış PDF'leri aranabilir hale getirebilir miyim?#

Bu zaten Paperless-ngx'in temel görevidir ve otomatik olarak yapılır. Sisteme yalnızca görsellerden oluşan, içinde seçilebilir metin bulunmayan bir PDF attığınızda, OCRmyPDF devreye girer ve belgenin arkasına görünmez bir metin katmanı ekleyerek onu tamamen aranabilir hale getirir. Orijinal dosyanız hiç bozulmadan saklanırken, arşiv kopyasının içinden metni kopyalayabilir ya da o metinde arama yapabilirsiniz. Yani eski, salt görsel taramalarınız bile arşive girdiği anda tam metin aramasına dahil olur.

Paperless-ngx ile Nextcloud arasındaki fark nedir?#

İki araç birbirinin rakibi değil, tamamlayıcısıdır. Nextcloud genel amaçlı bir bulut depolama ve dosya senkronizasyon platformudur; her türlü dosyayı saklar ama belgelerin içeriğini anlamaz. Paperless-ngx ise yalnızca belgelere odaklanır ve onları OCR, etiketleme ve tam metin aramayla akıllı bir arşive dönüştürür. Pek çok kullanıcı ikisini birlikte çalıştırır: dosyaları Nextcloud'da toplayıp belge niteliğindekileri Paperless'a besler. Konuyu detaylandıran Nextcloud rehberimize göz atabilirsiniz.

Belgelerimi başka bir sisteme taşımam gerekirse ne olur?#

Paperless-ngx sizi kendine hapsetmez, bu da onun en güçlü yanlarından biridir. Orijinal belgeleriniz her zaman standart PDF, JPG ya da PNG formatında, düz bir dizinde saklanır; hiçbir özel formata dönüştürülmez. document_exporter komutuyla tüm arşivinizi metadatasıyla birlikte taşınabilir dosyalar halinde dışa aktarabilir, istediğiniz zaman başka bir sunucuya ya da başka bir sisteme taşıyabilirsiniz. Verileriniz her zaman sizindir ve okunabilir kalır; bu yüzden gelecekte platform değiştirme kaygısı yaşamazsınız.

Kapanış#

Paperless-ngx, kağıt kaosunu düzenli ve aranabilir bir dijital hafızaya çeviren, olgun ve güvenilir bir çözümdür. OCR ile her belgenin içini okuyup otomatik etiketlemesi, tüketim klasörüyle taramaları kendiliğinden içeri alması ve güçlü aramasıyla, "o belge neredeydi?" sorusunu hayatınızdan tamamen çıkarır. Docker Compose sayesinde kurulumu da göründüğü kadar zor değildir; birkaç dosya ve tek bir komutla çalışır hale gelir.

Kendi belge arşivinizi kurmaya hazırsanız, bu iş için sağlam ve kesintisiz bir barındırma ortamına ihtiyacınız olacak. Yönetim özgürlüğü ve performans için bir VDS sunucu ya da esnek bir sanal sunucu Paperless-ngx için ideal bir temel sunar. Sunucunun güncelleme, yedekleme ve güvenlik tarafını profesyonellere bırakmak isterseniz sunucu yönetimi hizmetimizle ilgilenebilir, belgelerinizi güvence altına almak için de yedekleme ve SSL çözümlerimize göz atabilirsiniz. Clou.TR ekibi olarak, kağıtsız ofis yolculuğunuzun her adımında altyapı ihtiyaçlarınıza destek olmaya hazırız.