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

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

VPS वर Paperless-ngx वापरल्याने स्कॅन केलेल्या कागदपत्रांच्या फोल्डरचे शोधण्यायोग्य आर्काइव्हमध्ये रूपांतर होते. तुम्ही एखादी PDF 'watched directory' मध्ये टाकली की, सर्व्हर त्यावर OCR (optical character recognition) चालवतो, मजकूर वेगळा करतो, तारीख आणि संबंधित व्यक्तीचा अंदाज घेतो आणि ती फाईल जतन करतो. ही स्थापना चार सेवा असलेल्या एका Docker Compose फाईलद्वारे केली जाते. त्यानंतरची सर्व प्रक्रिया कॉन्फिगरेशनची आहे आणि या मार्गदर्शिकेचा बराचसा भाग याच विषयावर आहे, कारण इन्स्टॉलेशन बहुतेकदा तिथेच बिघडतात. हे फोटो लायब्ररी नाही: OCR आणि संबंधित व्यक्तीचा अंदाज लावण्याचे तंत्र सुट्ट्यांमधील JPEG फोटोंसाठी उपयुक्त नाही, त्यामुळे ते त्यांच्यासाठी बनवलेल्या फोटो सर्व्हरवर ठेवा आणि Paperless फक्त कागदपत्रांसाठी वापरा.

Paperless-ngx हा मूळ Paperless प्रकल्पाचा देखभाल केली जाणारा community fork आहे. तो विनामूल्य आणि self-hosted आहे. तो तुमची कागदपत्रे disk वरील plain files म्हणून साठवतो. त्यामुळे तुमच्या स्वतःच्या archive वर तुमचा प्रवेश कधीही बंद होत नाही. तो home box ऐवजी VPS वर चालवल्यास तुमचे scans कुठूनही उपलब्ध राहतात आणि home router वर port उघडण्याची गरज पडत नाही. कागदपत्रे नसलेल्या files साठी private Nextcloud instance सोबत ही रचना चांगली काम करते. तुमचा scanner जोडलेला desktop याच पद्धतीने हाताळता येतो. त्या VPS वर स्वतःचा RustDesk relay असल्यास router मध्ये hole न करता तुम्ही ती मशीन अन्य ठिकाणाहून नियंत्रित करू शकता.

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

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

• webserver: स्वतः paperless-ngx इमेज. हे वेब इंटरफेस, API, तुमच्या इनपुट फोल्डरवर लक्ष ठेवणारा कन्झ्युमर आणि OCR करणारे Celery टास्क वर्कर्स चालवते.
• db: PostgreSQL. हे मेटाडेटा, टॅग्स, पत्रव्यवहार करणारे (correspondents) आणि फुल-टेक्स्ट सर्च इंडेक्स टेबल साठवते. यात तुमच्या 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. हे नाव प्रत्येक कंटेनर आणि व्हॉल्यूमसाठी प्रीफिक्स (prefix) म्हणून वापरले जाते. त्यामुळे ती फाइल डिलीट करू नका, अन्यथा docker compose down -v ला तुमचा डेटा का सापडत नाही, असा प्रश्न तुम्हाला पडू शकतो.

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

दोन सेटिंग्ज ऐच्छिक नाहीत. प्रोजेक्टच्या दस्तऐवजीकरणानुसार खालील कमांड वापरून secret key तयार करा:

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

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 फोल्डरमध्ये कॉपी केलेल्या फाइल्स consumer ला वाचता येणार नाहीत आणि लॉगमध्ये इम्पॉर्टऐवजी permission एरर दिसेल.

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

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

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

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

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:// पत्त्यावर सेट केलेले असणे.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

export/manifest.json अस्तित्वात आहे आणि फाइलची संख्या interface मधील तुमच्या document count शी जुळते, हे तपासून backup ची पडताळणी करा. तुम्ही कधीही सूचीबद्ध केलेला नाही असा backup म्हणजे backup नाही. शांतपणे अपयशी होऊ लागणारा nightly export त्याहूनही धोकादायक असतो. त्यामुळे cron job कडून त्याचा exit status तुमच्या स्वतःच्या ntfy server कडे पाठवण्याची व्यवस्था करा. मग restore आवश्यक असलेल्या दिवशी नव्हे, तर तो अपयशी ठरलेल्या आठवड्यातच तुम्हाला याची माहिती मिळेल.

FAQ

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

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

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

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

मी PostgreSQL ऐवजी SQLite सह paperless-ngx चालवू शकतो का?

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

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

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

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

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