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 वेरिएंट में मौजूद। ये Office दस्तावेज़ों (.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 की बुनियादी बातें से शुरुआत करें और फिर वापस आएँ।
• एक डोमेन नाम जिसका A रिकॉर्ड आपके VPS पर पॉइंट कर रहा हो। Paperless ऐसे होस्टनेम पर सेवा देने से इनकार कर देता है जिसके बारे में उसे जानकारी न हो, इसलिए यह अपेक्षा से अधिक महत्वपूर्ण है।
• मेमोरी मुख्य बाधा है। PostgreSQL, Valkey, gunicorn और Tesseract OCR वर्कर एक साथ चलने पर हल्के उपयोग के लिए 2 GB में फिट हो जाते हैं। यदि आप सैकड़ों स्कैन का बैकलाग इम्पोर्ट करने की योजना बना रहे हैं, तो इसे 4 GB दें, क्योंकि बड़े मल्टी-पेज PDF पर OCR करने से मेमोरी में अचानक वृद्धि होती है जिससे वर्कर को kernel 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 को कॉन्फ़िगर करें

दो सेटिंग्स वैकल्पिक नहीं हैं। प्रोजेक्ट के दस्तावेज़ों में दिए गए कमांड के साथ सीक्रेट की (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 होता है। यह सेशन कुकीज़ को साइन करता है, इसलिए इसे ऐसे ही छोड़ देने का मतलब है कि कोई भी व्यक्ति जिसे डिफ़ॉल्ट मान पता है, वह सेशन को फ़ोर्ज (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 फ़ोल्डर में कॉपी की गई फ़ाइलें कंज्यूमर द्वारा नहीं पढ़ी जा सकेंगी, और लॉग में इम्पोर्ट के बजाय परमिशन एरर दिखाई देगा।

स्टैक शुरू करें और पहला उपयोगकर्ता बनाएं

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 (ट्रांसपोर्ट लेयर सिक्योरिटी) को टर्मिनेट करें और 127.0.0.1:8000 पर फॉरवर्ड करें। यदि यह बॉक्स पर एकमात्र ऐप है, तो ACME (ऑटोमैटिक सर्टिफिकेट मैनेजमेंट एनवायरनमेंट) क्लाइंट वाला कोई भी प्रॉक्सी काम करेगा। यदि आप एक सर्टिफिकेट सेटअप के पीछे कई कंटेनर चला रहे हैं, तो मल्टीपल 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 फ़ाइल compose डायरेक्टरी से ./consume को कंटेनर में 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 अपना स्वयं का एक्सपोर्टर प्रदान करता है, जो दस्तावेजों और सभी मेटाडेटा के 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 मौजूद है और फाइलों की संख्या इंटरफ़ेस में आपके दस्तावेज़ों की संख्या से मेल खाती है। जिस बैकअप को आपने कभी चेक नहीं किया है, वह बैकअप नहीं है।

FAQ

डोमेन को पॉइंट करने के बाद हर पेज "Bad Request (400)" क्यों दिखाता है?

Django ने Host हेडर को अस्वीकार कर दिया है क्योंकि आपका डोमेन ALLOWED_HOSTS में नहीं है। 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 कंटेनरों की आवश्यकता है?

केवल तभी जब आप चाहते हैं कि Word, Excel या OpenDocument फ़ाइलें आपकी PDF के साथ इंडेक्स हों। वे उन प्रारूपों को PDF में बदलते हैं ताकि paperless उन्हें OCR कर सके और खोज सके। वे दो और चल रहे कंटेनर और कुछ सौ मेगाबाइट मेमोरी भी जोड़ते हैं, इसलिए यदि आप जो कुछ भी फ़ाइल करते हैं वह पहले से ही PDF या इमेज है, तो छोटे बॉक्स पर उन्हें छोड़ दें।