VPS वर Paperless-ngx कसे इन्स्टॉल करावे

तुम्ही काय तयार करत आहात

VPS वरील Paperless-ngx स्कॅन केलेल्या कागदपत्रांच्या फोल्डरला शोधण्यायोग्य संग्रहणामध्ये रूपांतरित करते. तुम्ही एखादी PDF फाईल एका वॉच केलेल्या डिरेक्टरीमध्ये टाकता, तेव्हा सर्व्हर त्यावर OCR (ऑप्टिकल कॅरेक्टर रिकग्निशन) चालवतो, मजकूर काढतो, तारीख आणि पत्रव्यवहार करणाऱ्याचा अंदाज घेतो आणि ती फाईल जतन करतो. हे इन्स्टॉलेशन चार सर्व्हिसेस असलेल्या एका Docker Compose फाईलद्वारे केले जाते. त्यानंतरची सर्व प्रक्रिया कॉन्फिगरेशनची आहे, आणि या मार्गदर्शकाचा मोठा भाग याच विषयावर आहे, कारण इन्स्टॉलेशनमध्ये त्रुटी याच ठिकाणी येतात.

Paperless-ngx हा मूळ Paperless प्रकल्पाचा देखभाल केला जाणारा कम्युनिटी फोर्क आहे. हे मोफत आणि सेल्फ-होस्टेड आहे, आणि तुमची कागदपत्रे डिस्कवर साध्या फाईल्सच्या स्वरूपात साठवते, त्यामुळे तुम्ही तुमच्या स्वतःच्या संग्रहापासून कधीही वंचित राहत नाही. ते होम बॉक्सऐवजी VPS वर चालवल्यामुळे, तुमच्या होम राउटरवर पोर्ट उघडल्याशिवाय तुमचे स्कॅन कोठूनही ॲक्सेस करता येतात, आणि ते कागदपत्रे नसलेल्या फाईल्ससाठी एका खाजगी Nextcloud इन्स्टन्ससोबत उत्तम प्रकारे काम करते.

स्टॅक प्रत्यक्षात काय चालवते

अधिकृत compose फाईल चार कंटेनर्स सुरू करते, आणि त्यातील प्रत्येक कंटेनर काय करतो हे समजून घेतल्यास लॉग वाचणे सोपे होते.

• webserver: स्वतः paperless-ngx इमेज. हे वेब इंटरफेस, API, तुमच्या इनपुट फोल्डरवर लक्ष ठेवणारा कन्झ्युमर आणि OCR करणारे Celery टास्क वर्कर्स चालवते.
• db: PostgreSQL. हे मेटाडेटा, टॅग्स, पत्रव्यवहार करणाऱ्या व्यक्तींची माहिती आणि फुल-टेक्स्ट सर्च इंडेक्स टेबल साठवते. हे तुमच्या PDF फाईल्स साठवत नाही.
• broker: Valkey, एक Redis-सुसंगत की-व्हॅल्यू स्टोअर. हे वेब प्रोसेस आणि वर्कर्स यांच्यातील टास्क क्यू (task queue) म्हणून काम करते.
• gotenberg आणि tika: ऐच्छिक, फक्त -tika compose प्रकारांमध्ये उपलब्ध. हे ऑफिस डॉक्युमेंट्स (.docx, .xlsx, .odt) चे PDF मध्ये रूपांतर करतात जेणेकरून paperless त्यांना इंडेक्स करू शकेल.

जुलै 2026 पर्यंत, postgres compose फाईल docker.io/library/postgres:18 आणि docker.io/valkey/valkey:9-alpine ला पिन करते, आणि ghcr.io/paperless-ngx/paperless-ngx:latest वरून ॲप पुल करते.

पूर्वअटी

• sudo ॲक्सेस असलेले एक Ubuntu 24.04 KVM VPS, ज्यावर Docker आणि Compose प्लगइन आधीच इन्स्टॉल केलेले असावे. जर हा भाग तुमच्यासाठी नवीन असेल, तर VPS साठी Docker Compose चे मूलभूत घटक पासून सुरुवात करा आणि त्यानंतर परत या.
• तुमच्या VPS कडे निर्देश करणारे A रेकॉर्ड असलेले एक डोमेन नाव. Paperless अशा होस्टनेमवर सेवा देण्यास नकार देते ज्याबद्दल त्याला माहिती दिलेली नाही, त्यामुळे हे तुमच्या अपेक्षेपेक्षा लवकर महत्त्वाचे ठरते.
• मेमरी ही खरी मर्यादा आहे. PostgreSQL, Valkey, gunicorn आणि Tesseract OCR वर्कर हे सर्व एकाच वेळी चालवण्यासाठी हलक्या वापरासाठी 2 GB मेमरी पुरेशी आहे. जर तुम्ही शेकडो स्कॅनचा बॅकलॉग इम्पोर्ट करण्याची योजना आखत असाल, तर 4 GB मेमरी द्या, कारण मोठ्या मल्टी-पेज PDF वर OCR प्रक्रिया करताना मेमरीचा वापर अचानक वाढतो, ज्यामुळे कर्नलचा out-of-memory killer वर्करला बंद करू शकतो.
• डिस्क: तुमची अर्काईव्ह दोनदा साठवली जाते, मूळ फाईल आणि OCR केलेली अर्काईव्ह PDF, त्यामुळे तुमच्या स्कॅनच्या आकाराच्या दुप्पट जागा गृहीत धरा.

अधिकृत compose फाइल्स मिळवा

येथे एक इंटरअॅक्टिव्ह इंस्टॉलर उपलब्ध आहे:

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

हे टूल तुम्हाला काही प्रश्न विचारते आणि तुमच्यासाठी फाइल्स तयार करते. स्वतः हाताने हे काम केल्यास तुम्हाला चार कमांड्स चालवाव्या लागतात, ज्यामुळे सर्व फाइल्स कुठे आहेत हे तुम्हाला समजते. सर्व्हर मेंटेनन्ससाठी हेच योग्य आहे.

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

याचे प्रकार एकाच डिरेक्टरीमध्ये उपलब्ध आहेत: docker-compose.sqlite.yml, docker-compose.mariadb.yml, आणि प्रत्येकाची एक -tika आवृत्ती. नवीन इंस्टॉलेशनसाठी postgres निवडा. काही शे डॉक्युमेंट्ससाठी SQLite ठीक आहे, परंतु PostgreSQL च्या तुलनेत फुल-टेक्स्ट सर्च इंडेक्स लवकर धीमा होतो.

.env फाइलमध्ये एक ओळ असते, ती म्हणजे COMPOSE_PROJECT_NAME=paperless. हे नाव प्रत्येक कंटेनर आणि व्हॉल्यूमसाठी प्रीफिक्स म्हणून वापरले जाते, त्यामुळे ते डिलीट करू नका. अन्यथा, docker compose down -v ला तुमचा डेटा का सापडत नाही, असा प्रश्न तुम्हाला पडेल.

पहिल्यांदा सुरू करण्यापूर्वी docker-compose.env कॉन्फिगर करा

दोन सेटिंग्ज अनिवार्य आहेत. प्रकल्पाच्या दस्तऐवजात दिलेल्या कमांडचा वापर करून सिक्रेट की तयार करा:

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

त्यानंतर docker-compose.env संपादित करा:

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 या लिटरली व्हॅल्यूसह येते. हे सेशन कुकीजवर स्वाक्षरी करते, त्यामुळे ते तसेच ठेवल्यास, डीफॉल्ट व्हॅल्यू माहित असलेली कोणतीही व्यक्ती सेशन बनावट तयार करू शकते. पहिल्यांदा सुरू करण्यापूर्वी हे सेट करा, कारण नंतर बदलल्यास सर्व वापरकर्ते लॉग आउट होतील.

PAPERLESS_URL हे सेटिंग तुमचा एक तास वाचवते. Paperless हे एक Django ॲप्लिकेशन आहे आणि Django प्रत्येक विनंतीच्या Host हेडरची पडताळणी करते. PAPERLESS_URL सेट करा आणि ते तुमच्यासाठी ALLOWED_HOSTS, CORS_ALLOWED_HOSTS आणि CSRF_TRUSTED_ORIGINS भरते. ते रिकामे ठेवल्यास आणि डोमेन सर्व्हरकडे पॉइंट केल्यास, प्रत्येक पेज Bad Request (400) एरर देईल आणि कंटेनर लॉगमध्ये DisallowedHost दिसेल. हे लिहिताना शेवटी स्लॅश किंवा पाथ देऊ नका.

USERMAP_UID आणि USERMAP_GID हे कंटेनर ज्या वापरकर्त्याच्या नावाने चालतो, ते सेट करतात. ते तुमच्या स्वतःच्या अकाउंटशी जुळणारे असावेत, जे तुम्ही id -u आणि id -g वापरून तपासू शकता. जर ते जुळत नसतील, तर तुम्ही consume फोल्डरमध्ये कॉपी केलेल्या फाइल्स कन्झ्युमरला वाचता येणार नाहीत आणि लॉगमध्ये इम्पोर्टऐवजी परमिशन एरर दिसेल.

स्टॅक सुरू करा आणि पहिला वापरकर्ता तयार करा

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

createsuperuser वापरकर्तानाव, ईमेल आणि पासवर्ड विचारते. यामध्ये कोणतेही डीफॉल्ट लॉगिन नसल्यामुळे, ही पायरी वगळल्यास तुम्ही अशा साइन-इन पेजवर पोहोचाल जिथे कोणतीही माहिती स्वीकारली जाणार नाही. ब्राउझरमध्ये तपासण्यापूर्वी सर्व्हर पोर्ट 8000 वर लिसन (listen) करत असल्याची लॉग लाईन येईपर्यंत प्रतीक्षा करा. पहिल्यांदा सुरू करताना डेटाबेस मायग्रेशन्स देखील रन होतात, ज्यासाठी एक किंवा दोन मिनिटे लागू शकतात.

डोमेन जोडण्यापूर्वी ते स्थानिक पातळीवर तपासा:

curl -I http://127.0.0.1:8000

302 कडून /accounts/login/ वर होणारे रिडायरेक्ट म्हणजे स्टॅक व्यवस्थित कार्यरत आहे.

HTTPS चा वापर करा

स्टॉक compose फाईल 8000:8000 पब्लिश करते, जे सर्व इंटरफेसवर बाइंड होते. सार्वजनिक VPS वर, हे तुमच्या संपूर्ण दस्तऐवज संग्रहाला साध्या HTTP द्वारे कोणालाही उपलब्ध करून देते. पोर्ट लाईन बदलून ती फक्त लूपबॅकवर बाइंड करा:

    ports:
      - "127.0.0.1:8000:8000"

त्यानंतर रिव्हर्स प्रॉक्सीमध्ये TLS (transport layer security) टर्मिनेट करा आणि 127.0.0.1:8000 वर फॉरवर्ड करा. जर हे सर्व्हरवरील एकमेव ॲप असेल, तर ACME (automatic certificate management environment) क्लायंट असलेला कोणताही प्रॉक्सी चालेल. जर तुम्ही एका सर्टिफिकेट सेटअपच्या मागे अनेक कंटेनर्स चालवत असाल, तर अनेक Docker Compose ॲप्ससाठी Traefik रिव्हर्स प्रॉक्सी पॅटर्न फॉलो करा आणि webserver सर्व्हिसला प्रॉक्सी नेटवर्कशी जोडा, ज्यामध्ये कोणताही पोर्ट पब्लिश केलेला नसेल.

तुम्ही कोणतीही प्रॉक्सी वापरली तरी, तिने X-Forwarded-Proto: https पाठवणे आवश्यक आहे. त्याशिवाय Django ला असे वाटते की विनंती HTTP द्वारे आली आहे, लॉगिन फॉर्मवरील ओरिजिन चेक अयशस्वी होतो आणि तुम्हाला योग्य दिसणाऱ्या पेजवर CSRF verification failed. Request aborted. मिळते. या दुरुस्तीचा दुसरा भाग म्हणजे PAPERLESS_URL हे तुम्ही ब्राउझरमध्ये टाईप केलेल्या अचूक https:// ॲड्रेसवर सेट केलेले असणे.

तसेच प्रॉक्सीची अपलोड साईज लिमिट वाढवा. जर प्रॉक्सी बॉडीजवर 1 MB ची मर्यादा घालत असेल, तर 40 MB चा स्कॅन paperless कडे पोहोचण्यापूर्वीच नाकारला जातो आणि ब्राउझर एक सामान्य अपलोड एरर दाखवतो.

consume डिरेक्टरी कशी कार्य करते

compose फाईल ./consume ला compose डिरेक्टरीमधून कंटेनरमध्ये bind-mount करते. तुम्ही तिथे जी काही फाईल टाकता, ती इम्पोर्ट केली जाते आणि त्यानंतर फोल्डरमधून हटवली जाते, कारण ती फाईल आता paperless व्यवस्थापनांतर्गत media व्हॉल्यूममध्ये साठवली जाते.

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

तुम्हाला consumer फाईलचे नाव उचलताना, OCR प्रक्रिया राबवताना आणि दस्तऐवज जोडला गेल्याचा अहवाल देणारी ओळ पूर्ण करताना दिसेल. एका पानाचे स्कॅन पूर्ण करण्यासाठी या संपूर्ण चक्राला काही सेकंद लागतात, तर मोठ्या दस्तऐवजासाठी एक मिनिट किंवा त्यापेक्षा जास्त वेळ लागू शकतो.

दोन सेटिंग्ज फाईल्स कशा शोधल्या जातात हे बदलतात. PAPERLESS_CONSUMER_RECURSIVE=true मुळे paperless सबफोल्डर्समध्ये शोध घेते आणि PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true प्रत्येक सबफोल्डरच्या नावाला टॅगमध्ये रूपांतरित करते, त्यामुळे जर तुम्ही एखादी फाईल consume/invoices/2026/ मध्ये टाकली, तर तिला invoices आणि 2026 हे टॅग्स लावले जातात. ही तुम्ही तयार केलेली सर्वात स्वस्त फाईलिंग सिस्टिम असेल.

डिटेक्शन हा दुसरा महत्त्वाचा भाग आहे. डीफॉल्टनुसार PAPERLESS_CONSUMER_POLLING_INTERVAL हे 0 असते, याचा अर्थ paperless कर्नल फाईलसिस्टिम नोटिफिकेशन्सचा वापर करते, जे त्वरित कार्यान्वित होतात. ही नोटिफिकेशन्स नेटवर्क फाईलसिस्टिमवर काम करत नाहीत. जर तुमचे consume फोल्डर NFS किंवा SMB शेअर असेल जेणेकरून नेटवर्क स्कॅनर त्यावर लिहू शकेल, तर काहीही डिटेक्ट होणार नाही. अशा वेळी, paperless ने फोल्डर स्कॅन करावे यासाठी इंटरव्हलला काही सेकंदांचा सकारात्मक आकडा सेट करणे हा उपाय आहे.

OCR भाषा आणि त्यांचा खर्च

PAPERLESS_OCR_LANGUAGE तीन अक्षरी Tesseract कोड घेते, जे डीफॉल्टनुसार eng असते. भाषा एकत्र करण्यासाठी अधिक चिन्हाचा (+) वापर करा, जसे की deu+eng मध्ये दिले आहे. त्यानंतर Tesseract प्रत्येक भाषेचा प्रयत्न करते आणि सर्वोत्तम निकाल निवडते, त्यामुळे प्रत्येक अतिरिक्त भाषेमुळे प्रत्येक पानावर खर्च होणारा CPU वेळ वाढतो. शेअर केलेल्या vCPU VPS वर, याचा परिणाम असा होतो की स्कॅन पूर्ण होण्यासाठी दहा सेकंदांऐवजी एक मिनिट लागू शकतो. तुमच्या दस्तऐवजांमध्ये ज्या भाषा प्रत्यक्ष वापरल्या आहेत, फक्त त्याच भाषांची यादी करा.

या इमेजमध्ये English, German, Italian, Spanish आणि French भाषा आधीच समाविष्ट आहेत. इतर कोणत्याही भाषेसाठी, ती भाषा PAPERLESS_OCR_LANGUAGES मध्ये स्पेसने वेगळी करून जोडा, उदाहरणार्थ PAPERLESS_OCR_LANGUAGES=tur ces, आणि कंटेनर रीस्टार्ट करा. कंटेनर स्टार्टअपच्या वेळी Tesseract डेटा पॅक डाउनलोड करतो, त्यामुळे हा बदल केल्यानंतर होणारा पहिला बूट संथ असतो.

डेटाबेस आणि मीडियाचा बॅकअप घेणे

PostgreSQL सुरू असताना Docker व्हॉल्यूम्सची प्रत तयार केल्यास असा बॅकअप मिळू शकतो जो कदाचित रिस्टोर होणार नाही. Paperless स्वतःचे एक्सपोर्टर (exporter) देते, जे दस्तऐवज आणि सर्व मेटाडेटाची JSON मॅनिफेस्ट ./export बाइंड माउंटमध्ये लिहिते:

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

--delete सध्याच्या दस्तऐवजाशी जुळत नसलेल्या एक्सपोर्ट केलेल्या फाइल्स काढून टाकते, त्यामुळे फोल्डरची वाढ होत न राहता ते एक मिरर (mirror) म्हणून राहते. जेव्हा हे cron मधून चालवले जाते, तेव्हा --no-progress-bar आउटपुट स्वच्छ ठेवते.

रिस्टोर करणे म्हणजे नवीन स्टॅकवर त्याच फोल्डरच्या विरुद्ध document_importer वापरणे, ज्याचा अर्थ असा की एक्सपोर्ट डिरेक्टरी ही एकमेव गोष्ट आहे जी तुम्हाला सुरक्षित ठेवणे आवश्यक आहे. तुमच्या VPS वरून एनक्रिप्टेड, डीडुप्लिकेटेड restic बॅकअप्स वापरून ते वेळापत्रकानुसार ऑफसाइट पाठवा आणि आधी एक्सपोर्ट चालवा जेणेकरून restic कधीही अर्धवट लिहिलेली अर्काइव्ह कॅप्चर करणार नाही.

export/manifest.json अस्तित्वात आहे आणि फाइल्सची संख्या इंटरफेस मधील तुमच्या दस्तऐवजांच्या संख्येशी जुळते याची खात्री करून बॅकअप तपासा. ज्या बॅकअपची तुम्ही कधीही पडताळणी केलेली नाही, तो बॅकअप नसतो.

FAQ

माझे डोमेन पॉइंट केल्यानंतर प्रत्येक पेज "Bad Request (400)" असा एरर का दाखवते?

तुमचे डोमेन ALLOWED_HOSTS मध्ये नसल्यामुळे Django ने Host हेडर नाकारले आहे. docker-compose.env मध्ये PAPERLESS_URL=https://paperless.example.com सेट करा, शेवटी स्लॅश नसावा, आणि त्यानंतर कंटेनर पुन्हा तयार करण्यासाठी docker compose up -d रन करा. फक्त env फाईल एडिट केल्याने काहीही होत नाही, कारण चालू असलेला कंटेनर सुरुवातीच्या एनवायरमेंट व्हेरिएबल्सचाच वापर करत राहतो.

मी consume फोल्डरमध्ये एक PDF टाकली पण काहीही घडले नाही. काय चूक आहे?

प्रथम docker compose logs webserver तपासा. परमिशन एररचा अर्थ असा आहे की USERMAP_UID आणि USERMAP_GID हे फाईलच्या मालकीच्या अकाउंटशी जुळत नाहीत, त्यामुळे ते दुरुस्त करा आणि कंटेनर पुन्हा तयार करा. जर लॉगमध्ये कोणतीही ओळ दिसत नसेल, तर याचा अर्थ फाईल इव्हेंट पोहोचलाच नाही; नेटवर्क शेअर्सवर असे घडते कारण कर्नल नोटिफिकेशन्स तिथे काम करत नाहीत. PAPERLESS_CONSUMER_POLLING_INTERVAL ला 30 सारख्या मूल्यावर सेट करा, म्हणजे paperless दर 30 सेकंदांनी फोल्डर स्कॅन करेल.

मी PostgreSQL ऐवजी SQLite वापरून paperless-ngx चालवू शकतो का?

हो, docker-compose.sqlite.yml समर्थित आहे आणि ते कमी मेमरी वापरते, जे लहान VPS साठी योग्य आहे. जसा तुमचा संग्रह वाढेल तसा याचा परिणाम दिसून येईल: हजारो डॉक्युमेंट्स झाल्यावर फुल-टेक्स्ट सर्च आणि बल्क टॅग एडिट्स लक्षणीयरीत्या मंदावतात. नंतर मायग्रेट करायचे असल्यास एक्सपोर्ट आणि इम्पोर्ट करावे लागेल, त्यामुळे जर तुमचा संग्रह वाढत राहणार असेल तर आताच PostgreSQL निवडा.

स्कॅन केलेल्या संग्रहासाठी प्रत्यक्षात किती डिस्क स्पेस लागते?

तुमच्या मूळ फाईल्सच्या आकाराच्या साधारण दुप्पट. Paperless मूळ फाईलमध्ये कोणताही बदल करत नाही आणि एक दुसरी OCR केलेली PDF साठवते ज्यामध्ये सर्च करण्यायोग्य टेक्स्ट लेयर आणि लहान थंबनेल्स असतात. केवळ मजकूर असलेल्या 200 KB स्कॅनचा आकार लहानच राहतो. मोठ्या कराराच्या 30 MB कलर स्कॅनसाठी सुमारे 60 MB जागा लागते. जर तुम्ही एक्सपोर्ट डिरेक्टरी त्याच डिस्कवर ठेवली, तर तोच संग्रह डिस्कवर तीनदा साठवला जातो.

मला Tika आणि Gotenberg कंटेनर्सची गरज आहे का?

केवळ जर तुम्हाला तुमच्या PDF सोबत Word, Excel किंवा OpenDocument फाईल्स इंडेक्स करायच्या असतील तरच. ते या फॉरमॅट्सना PDF मध्ये रूपांतरित करतात जेणेकरून paperless त्यांचे OCR करून सर्च करू शकेल. यामुळे दोन अतिरिक्त कंटेनर्स चालू राहतात आणि काहीशे मेगाबाइट मेमरी वापरली जाते, त्यामुळे जर तुम्ही फक्त PDF किंवा इमेजेस फाईल करत असाल तर लहान सर्व्हरवर हे टाळा.