SSD Nodes Learn Hosting plans →
Rehberler Matt ConnorYazan Matt Connor · Güncellendi 2026-10-23

VPS Uzerinde Paperless-ngx Kurulumu ve Yapilandirma

Docker Compose ile VPS uzerinde Paperless-ngx kurulumunu ogrenin. Postgres stack, PAPERLESS_URL ayari, OCR dilleri, HTTPS yapilandirmasi ve veri yedekleme adimlarini inceleyin.

Ne inşa ediyorsunuz

Bir VPS üzerinde çalışan Paperless-ngx, taranmış kağıtlardan oluşan bir klasörü aranabilir bir arşive dönüştürür. Bir PDF dosyasını izlenen bir dizine bıraktığınızda, sunucu üzerinde OCR (optik karakter tanıma) çalıştırır, metni çıkarır, bir tarih ve gönderici tahmini yapar ve dosyalar. Kurulum, dört servisten oluşan tek bir Docker Compose dosyasından ibarettir. Bundan sonraki her şey yapılandırmadır ve bu rehberin büyük bir kısmı buna ayrılmıştır, çünkü kurulumlar genellikle burada hata verir. Bu bir fotoğraf kütüphanesi değildir: OCR ve gönderici tahmini, tatil fotoğraflarından oluşan bir klasör için hiçbir işe yaramaz; bu yüzden onları bunun için oluşturulmuş bir fotoğraf sunucusuna koyun ve paperless'ı kağıtlar için kullanın. Video için de aynı kural geçerlidir: kopyalanmış filmlerden oluşan bir raf, bir medya sunucusuna aittir; burada 90'ların video kiralama dükkanı gibi tasarlanmış bir Jellyfin arayüzü, arama yapmaktan ziyade göz atmayı ön plana çıkarır.

Paperless-ngx, orijinal Paperless projesinin topluluk tarafından sürdürülen güncel çatalıdır (fork). Ücretsizdir, self-hosted olarak çalışır ve belgelerinizi diskte düz dosyalar olarak saklar; böylece arşivinize erişiminiz hiçbir zaman kısıtlanmaz. Evdeki bir cihaz yerine VPS üzerinde çalıştırmak, taramalarınıza evdeki yönlendiricinizde (router) port açmadan her yerden ulaşabileceğiniz anlamına gelir ve bu yapı kağıt olmayan dosyalar için özel bir Nextcloud kurulumu ile iyi bir uyum sağlar. Aynı mantık, tarayıcınızın bağlı olduğu masaüstü bilgisayar için de geçerlidir; kendi VPS'inizdeki bir RustDesk aktarıcısı, yönlendiricinizde delik açmadan o makineyi başka bir yerden yönetmenize olanak tanır.

Yığının gerçekte ne çalıştırdığı

Resmi compose dosyası dört container başlatır; her birinin ne işe yaradığını bilmek, logların okunabilir olmasını sağlar.

  • webserver: paperless-ngx imajının kendisi. Web arayüzünü, API'yi, girdi klasörünüzü izleyen tüketiciyi ve OCR işlemlerini gerçekleştiren Celery görev çalışanlarını (task workers) çalıştırır.
  • db: PostgreSQL. Meta verileri, etiketleri, yazışmaları ve tam metin arama dizin tablolarını tutar. PDF dosyalarınızı burada tutmaz.
  • broker: Valkey, Redis uyumlu bir anahtar-değer deposu. Web süreci ile çalışanlar arasındaki görev kuyruğudur.
  • gotenberg ve tika: isteğe bağlıdır, yalnızca -tika compose varyantlarında bulunur. Office belgelerini (.docx, .xlsx, .odt) PDF'e dönüştürürler, böylece paperless bunları dizine ekleyebilir.

Ekim 2026 itibarıyla, postgres compose dosyası docker.io/library/postgres:18 ve docker.io/valkey/valkey:9-alpine sürümlerini sabitler ve uygulamayı ghcr.io/paperless-ngx/paperless-ngx:latest adresinden çeker.

Ön gereksinimler

  • Sudo erişimine sahip bir Ubuntu 24.04 KVM VPS ve halihazırda kurulu Docker Compose eklentisi. Bu kısım sizin için yeniyse, VPS için Docker Compose temelleri ile başlayıp buraya geri dönün.
  • VPS'in IP adresini işaret eden bir A kaydına sahip alan adı. Paperless, kendisine tanımlanmamış bir ana bilgisayar adı üzerinden HTTPS ile oturum açma isteğini kabul etmeyecektir; bu nedenle bu konu beklediğinizden daha erken önem kazanır.
  • Bellek, asıl kısıtlayıcı faktördür. PostgreSQL, Valkey, Granian web sunucusu ve Tesseract OCR işleyicisi aynı anda çalışırken hafif kullanımda 2 GB bellek yeterlidir. Yüzlerce taramadan oluşan bir birikimi içe aktarmayı planlıyorsanız 4 GB bellek ayırın; çünkü büyük ve çok sayfalı PDF dosyalarında OCR işlemi, bellek kullanımında ani artışlara yol açarak işleyicinin çekirdek tarafından "out-of-memory" (bellek yetersizliği) nedeniyle sonlandırılmasına neden olabilir.
  • Disk: Arşiviniz, orijinal dosya ve OCR işleminden geçmiş arşiv PDF'i olmak üzere iki kez saklanır; bu nedenle taramalarınızın toplam boyutunun yaklaşık iki katı kadar disk alanı ayırın.

Resmi compose dosyalarını edinme

Etkileşimli bir yükleyici mevcuttur:

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Bu yükleyici size sorular sorar ve dosyaları sizin yerinize oluşturur. İşlemi manuel olarak yapmak dört komut sürer ve her şeyin nerede olduğunu bilmenizi sağlar; yönettiğiniz bir sunucuda istediğiniz durum tam olarak budur.

mkdir -p ~/paperless && cd ~/paperless
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -fsSL -o docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -fsSL -o .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

Varyantlar aynı dizinde bulunur: docker-compose.sqlite.yml, docker-compose.mariadb.yml ve her birinin bir -tika sürümü. Yeni bir kurulum için postgres seçin. SQLite birkaç yüz doküman için uygundur ancak tam metin arama dizini, PostgreSQL'den çok daha önce yavaşlamaya başlar.

.env dosyası tek bir satır içerir: COMPOSE_PROJECT_NAME=paperless. Bu isim, her container ve volume için önek haline gelir; bu yüzden dosyayı silmeyin, aksi takdirde docker compose down -v neden verilerinizi bulamıyor diye merak edersiniz.

İlk başlatmadan önce docker-compose.env dosyasını yapılandırın

İki ayar isteğe bağlı değildir. Proje belgelerinde belirtilen komutu kullanarak gizli anahtarı oluşturun:

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

Ardından docker-compose.env dosyasını düzenleyin:

PAPERLESS_SECRET_KEY=<the long string you just generated>
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
USERMAP_UID=1000
USERMAP_GID=1000

PAPERLESS_SECRET_KEY, change-me sabit değeriyle gelir. Bu değer oturum belirteçlerini imzalar ve güncel sürümler bu yer tutucuyu ayarlanmamış olarak kabul eder: paperless, anahtar eksik, boş veya hala change-me olduğunda başlamayı reddeder; bu nedenle anahtarı değiştirene kadar yığın ayağa kalkmayacaktır. Anahtarı ilk başlatmadan önce ayarlayın, çünkü daha sonra değiştirmek tüm kullanıcıların oturumunu kapatır.

PAPERLESS_URL, size bir saat kazandıracak olan ayardır. Paperless bir Django uygulamasıdır ve Django hem Host başlığını hem de giriş formunda tarayıcının bildirdiği kaynağı (origin) kontrol eder. PAPERLESS_URL değerini ayarladığınızda, adresinizi sizin yerinize ALLOWED_HOSTS, CORS_ALLOWED_HOSTS ve CSRF_TRUSTED_ORIGINS içine ekler. Bu alanı boş bırakıp bir alan adını sunucuya yönlendirirseniz, PAPERLESS_ALLOWED_HOSTS varsayılan olarak * değerini aldığı için giriş sayfası yüklenir; ancak HTTPS üzerinden gönderim yapıldığında, alan adınız güvenilir bir kaynak olmadığı için CSRF verification failed. Request aborted. hatası alırsınız. Bu değeri sonunda eğik çizgi (slash) veya yol olmadan yazın.

USERMAP_UID ve USERMAP_GID, container'ın hangi kullanıcı yetkileriyle çalışacağını belirler. Bu değerleri, id -u ve id -g komutlarıyla kontrol edebileceğiniz kendi kullanıcı hesabınızla eşleştirin. Eğer değerler eşleşmezse, consume klasörüne kopyaladığınız dosyalar tüketici (consumer) tarafından okunamaz ve günlük kayıtlarında içe aktarma hatası yerine bir izin hatası görünür.

Yığını başlatın ve ilk kullanıcıyı oluşturun

docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webserver

createsuperuser bir kullanıcı adı, e-posta adresi ve parola ister. Varsayılan bir giriş bilgisi yoktur. Bu adımı atlarsanız, web arayüzü ilk açan kişiden süper kullanıcıyı oluşturmasını ister. 8000 numaralı port internete açık olduğu sürece bu kişi siz olmayabilirsiniz, bu yüzden hesabı hemen shell üzerinden oluşturun. Tarayıcıyı denemeden önce sunucunun 8000 numaralı portu dinlediğini belirten log satırını bekleyin. İlk başlatma işlemi aynı zamanda veritabanı migrasyonlarını da çalıştırır; bu işlem bir veya iki dakika sürer.

Bir alan adı eklemeden önce yerel olarak kontrol edin:

curl -I http://127.0.0.1:8000

302 üzerinden /accounts/login/ adresine yönlendirme yapılması, yığının sağlıklı çalıştığı anlamına gelir.

Önüne HTTPS ekleyin

Varsayılan compose dosyası 8000:8000 portunu dışarı açar ve tüm ağ arayüzlerine bağlar. Bu durum, herkese açık bir VPS üzerinde tüm belge arşivinizin, adresi bulan herkes için şifrelenmemiş HTTP üzerinden sunulmasına neden olur. Port satırını yalnızca loopback arayüzüne bağlanacak şekilde değiştirin:

    ports:
      - "127.0.0.1:8000:8000"

Ardından TLS (transport layer security) sonlandırma işlemini bir reverse proxy üzerinde gerçekleştirin ve trafiği 127.0.0.1:8000 adresine yönlendirin. Eğer sunucuda yalnızca bu uygulama çalışıyorsa, ACME (automatic certificate management environment) istemcisine sahip herhangi bir proxy yeterli olacaktır. Tek bir sertifika yapısı arkasında birden fazla container çalıştırıyorsanız, birden fazla Docker Compose uygulaması için Traefik reverse proxy modeli rehberini takip edin ve webserver servisini hiçbir port yayınlamadan proxy ağına dahil edin.

Hangi proxy'yi kullanırsanız kullanın, giriş formunun origin kontrolü, HTTPS kurulumlarının genellikle hata verdiği noktadır. Paperless, PAPERLESS_PROXY_SSL_HEADER ayarı etkinleştirilmediği sürece X-Forwarded-Proto değişkenini dikkate almaz. Bu ayar varsayılan olarak kapalıdır; dolayısıyla Django, proxy üzerinden gelen her isteği şifrelenmemiş HTTP olarak değerlendirir ve tarayıcınızın gönderdiği https:// origin bilgisi, yalnızca güvenilir listesinde yer alıyorsa kabul edilir. PAPERLESS_URL değişkenini tarayıcıya yazdığınız tam https:// adresiyle yapılandırmak, bu adresi güvenilir listesine ekler. Aksi takdirde, görsel olarak doğru görünen bir sayfada CSRF verification failed. Request aborted. hatası alırsınız.

Ayrıca proxy'nizin dosya yükleme boyutu sınırını yükseltin. Proxy üzerinden gönderilen 40 MB boyutundaki bir tarama dosyası, eğer proxy gövde boyutunu 1 MB ile sınırlandırıyorsa, Paperless'a ulaşamadan reddedilir ve tarayıcı genel bir yükleme hatası bildirir.

Consume dizini nasıl çalışır

Compose dosyası, ./consume dizinini compose dizininden container içine bind-mount yöntemiyle bağlar. Buraya koyduğunuz her dosya içe aktarılır ve ardından klasörden silinir; çünkü dosya artık paperless yönetimi altındaki medya biriminde yaşamaktadır.

cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserver

Consumer'ın dosya adını aldığını, OCR işlemini çalıştırdığını ve belgenin eklendiğini bildiren bir satırla işlemi tamamladığını görmelisiniz. Tüm döngü, tek sayfalık bir tarama için saniyeler sürerken, uzun bir belge için bir dakika veya daha fazla sürebilir.

İki ayar, dosyaların nasıl bulunacağını değiştirir. PAPERLESS_CONSUMER_RECURSIVE=true, paperless'ın alt klasörlere bakmasını sağlar; PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true ise her alt klasör adını bir etikete dönüştürür. Bu sayede bir dosyayı consume/invoices/2026/ içine bırakmak, onu invoices ve 2026 olarak etiketler. Bu, kurabileceğiniz en düşük maliyetli dosyalama sistemidir.

Algılama, işin diğer yarısıdır. Varsayılan olarak PAPERLESS_CONSUMER_POLLING_INTERVAL değeri 0 şeklindedir; bu, paperless'ın anında tetiklenen yerel dosya sistemi bildirimlerini kullandığı anlamına gelir. Bu bildirimler ağ dosya sistemlerinde güvenilir değildir. Eğer consume klasörünüz bir ağ tarayıcısının yazabilmesi için NFS veya SMB paylaşımı ise, dosyalar algılanmadan orada bekleyebilir. Bunun çözümü, aralığı pozitif bir saniye değerine ayarlayarak paperless'ın klasörü düzenli olarak taramasını sağlamaktır.

OCR dilleri ve maliyetleri

PAPERLESS_OCR_LANGUAGE, üç harfli bir Tesseract kodu alır; varsayılan değer eng şeklindedir. Dilleri, deu+eng örneğinde olduğu gibi artı işaretiyle birleştirebilirsiniz. Tesseract, bu durumda her sayfada listelenen tüm dillerle işlem yapar; dolayısıyla eklenen her dil, her tarama için CPU süresini artırır. Paylaşımlı vCPU kullanan bir VPS üzerinde bu durum, taramanın on saniyede bitmesi ile bir dakikada bitmesi arasındaki farkı yaratır. Yalnızca belgelerinizin gerçekten yazılı olduğu dilleri listeleyin.

İmaj; İngilizce, Almanca, İtalyanca, İspanyolca ve Fransızca dilleriyle gelir. Başka bir dil için, dili PAPERLESS_OCR_LANGUAGES değişkenine boşlukla ayrılmış bir liste olarak ekleyin (örneğin PAPERLESS_OCR_LANGUAGES=tur ces) ve servisi yeniden başlatın. Container, Tesseract veri paketlerini başlatma sırasında indirir; bu nedenle değişiklikten sonraki ilk açılış daha yavaş gerçekleşir.

Veritabanını ve medyayı yedekleme

PostgreSQL çalışırken Docker birimlerini kopyalamak, geri yüklenemeyebilecek bir yedek oluşturmanıza neden olur. Paperless, belgeleri ve tüm meta verileri içeren bir JSON manifestosunu ./export bind mount dizinine yazan kendi dışa aktarma aracını sunar:

docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar

--delete, artık mevcut bir belgeyle eşleşmeyen dışa aktarılmış dosyaları kaldırır; böylece klasör sürekli büyümek yerine bir yansıma olarak kalır. --no-progress-bar, bu işlem cron üzerinden çalıştırıldığında çıktıyı temiz tutar ve -T, Compose'un cron'da bulunmayan bir terminal istemesini engeller.

Geri yükleme işlemi, yeni bir yığın üzerinde aynı klasöre karşı document_importer ile yapılır; bu da dışa aktarma dizininin güvenli tutmanız gereken tek şey olduğu anlamına gelir. Bu dizini VPS'inizden şifrelenmiş, tekilleştirilmiş restic yedekleri ile düzenli olarak uzak bir konuma gönderin ve restic'in yarım yazılmış bir arşivi yakalamaması için dışa aktarma işlemini önce çalıştırın.

export/manifest.json dosyasının var olduğunu ve dosya sayısının arayüzdeki belge sayınızla eşleştiğini kontrol ederek yedeği doğrulayın. Hiç listelemediğiniz bir yedek, yedek değildir. Sessizce başarısız olmaya başlayan bir gece dışa aktarma işlemi daha da kötüdür; bu nedenle cron işinin çıkış durumunu kendi ntfy sunucunuza göndermesini sağlayın. Böylece sistem bozulduğunda, geri yükleme yapmanız gereken günü beklemeden durumu o hafta öğrenebilirsiniz.

FAQ

Alan adımı yönlendirdikten sonra neden her sayfa "Bad Request (400)" hatası veriyor?

Varsayılan dosyalarla bu durumun yaşanmaması gerekir, çünkü PAPERLESS_ALLOWED_HOSTS varsayılan olarak * değerini kullanır. Konteyner günlüğünde DisallowedHost içeren bir 400, PAPERLESS_ALLOWED_HOSTS değerinin alan adınızı dışarıda bırakan bir listeye ayarlandığı anlamına gelir. docker-compose.env dosyasında PAPERLESS_URL=https://paperless.example.com değerini sonunda eğik çizgi (slash) olmadan ayarlayın; paperless bu ana makine adını listeye ekleyecektir. Alternatif olarak PAPERLESS_ALLOWED_HOSTS satırını kaldırın. Ardından konteyneri yeniden oluşturmak için docker compose up -d komutunu çalıştırın. Yalnızca env dosyasını düzenlemek bir sonuç vermez, çünkü çalışan konteyner başlatıldığı andaki ortam değişkenlerini korur.

consume klasörüne bir PDF attım ancak hiçbir şey olmadı. Sorun nedir?

Öncelikle docker compose logs webserver dosyasını kontrol edin. Bir izin hatası, USERMAP_UID ve USERMAP_GID değerlerinin dosyanın sahibi olan hesapla eşleşmediği anlamına gelir; bunları düzeltin ve konteyneri yeniden oluşturun. Günlükte hiçbir satır görünmüyorsa dosya olayı hiç ulaşmamış demektir; bu durum ağ paylaşımlarında yaşanır çünkü yerel dosya sistemi bildirimleri ağ üzerinde güvenilir değildir. PAPERLESS_CONSUMER_POLLING_INTERVAL değerini 30 gibi bir süreye ayarlarsanız, paperless klasörü her 30 saniyede bir tarayacaktır.

paperless-ngx uygulamasını PostgreSQL yerine SQLite ile çalıştırabilir miyim?

Evet, docker-compose.sqlite.yml desteklenmektedir ve daha az bellek tüketir; bu da küçük bir VPS için uygundur. Arşiviniz büyüdükçe performans kaybı yaşanır: binlerce belgelik bir arşivde tam metin araması ve toplu etiket düzenlemeleri belirgin şekilde yavaşlar. Daha sonra geçiş yapmak dışa ve içe aktarma gerektirir, bu nedenle arşivinizin büyüyeceğini öngörüyorsanız şimdiden PostgreSQL seçin.

Tarama arşivim ne kadar disk alanına ihtiyaç duyar?

Kaynak dosyalarınızın boyutunun yaklaşık iki katı kadar. Paperless orijinal dosyayı değiştirmeden saklar ve ikinci bir OCR işleminden geçmiş, aranabilir metin katmanına sahip bir PDF ile küçük önizleme görselleri oluşturur. Sadece metin içeren 200 KB boyutundaki bir tarama küçük kalır. Uzun bir sözleşmenin 30 MB boyutundaki renkli taraması yaklaşık 60 MB yer kaplar. Eğer dışa aktarma (export) dizinini aynı diskte tutuyorsanız, aynı arşiv diskte üç kez yer kaplamış olur.

Tika ve Gotenberg konteynerlerine ihtiyacım var mı?

Yalnızca Word, Excel veya OpenDocument dosyalarınızın PDF'lerinizle birlikte indekslenmesini istiyorsanız gereklidir. Bu servisler, paperless uygulamasının OCR yapabilmesi ve arama gerçekleştirebilmesi için söz konusu formatları PDF'e dönüştürür. Ayrıca iki ek konteyner çalıştırırlar ve birkaç yüz megabayt bellek tüketirler; bu nedenle arşivlediğiniz her şey zaten PDF veya görsel ise küçük bir sunucuda bunları kullanmayabilirsiniz.

Bu yazı işinize yaradı mı?

#paperless-ngx#documents#self-hosting#docker#ocr