VPS वर Paperless-ngx कसे इन्स्टॉल करावे
Docker Compose वापरून VPS वर Paperless-ngx सेटअप करण्याची संपूर्ण माहिती. यामध्ये Postgres डेटाबेस, OCR भाषा सेटिंग्ज, HTTPS सुरक्षा आणि बॅकअप घेण्याच्या पद्धती स्पष्ट केल्या आहेत.
तुम्ही काय तयार करत आहात
VPS वर Paperless-ngx चालवल्यास स्कॅन केलेल्या कागदपत्रांचे एक searchable archive तयार होते. तुम्ही PDF watched directory मध्ये ठेवता. त्यानंतर server त्यावर OCR (optical character recognition) चालवतो, मजकूर काढतो, तारीख आणि संबंधित व्यक्तीचा अंदाज लावतो आणि कागदपत्राची नोंद करतो. ही install चार services असलेल्या एका Docker Compose file ने होते. त्यानंतरचे सर्व काम configuration चे असते. या मार्गदर्शकाचा बहुतांश भाग त्यासाठी दिला आहे, कारण installs बहुतेकदा याच टप्प्यावर fail होतात. हे photo library नाही. OCR आणि correspondent guessing मुळे सुट्टीतील JPEG files असलेल्या directory चा उपयोग होत नाही. त्यामुळे त्या त्यांच्यासाठी तयार केलेल्या photo server मध्ये ठेवा आणि Paperless चा वापर कागदपत्रांसाठी करा. Video साठीही हेच लागू होते. Ripped films चा संग्रह media server वर ठेवावा. तेथे 90s rental store सारखा सजवलेला Jellyfin front end browsing ला महत्त्व देतो, केवळ searching ला नाही.
Paperless-ngx हा मूळ Paperless project चा maintained community fork आहे. तो free आणि self-hosted आहे. तुमची documents disk वर plain files म्हणून साठवली जातात. त्यामुळे तुमच्या स्वतःच्या archive वरचा प्रवेश कधीही बंद होत नाही. Home box ऐवजी VPS वर तो चालवल्यास home router वर port न उघडता scans कुठूनही उपलब्ध होतात. तसेच कागदपत्रे नसलेल्या files साठी private Nextcloud instance सोबत त्याचा चांगला वापर करता येतो. तुमचा scanner ज्या desktop ला जोडलेला आहे त्यालाही हेच लागू होते. त्या मशीनवर इतर ठिकाणाहून नियंत्रण ठेवण्यासाठी त्या VPS वरचा तुमचा स्वतःचा RustDesk relay वापरता येतो. यासाठी router मध्ये port उघडण्याची गरज नसते.
स्टॅक प्रत्यक्षात काय चालवतो
अधिकृत compose फाइल चार containers सुरू करते. प्रत्येक container काय करतो हे समजल्यास logs वाचणे सोपे होते.
webserver: paperless-ngx image स्वतः. हे web interface, API, तुमचे input folder पाहणारा consumer आणि OCR करणारे Celery task workers चालवते.db: PostgreSQL. यात metadata, tags, correspondents आणि full-text search index tables साठवले जातात. तुमच्या PDFs यात साठवल्या जात नाहीत.broker: Valkey, Redis-सुसंगत key-value store. हे web process आणि workers यांच्यातील task queue आहे.gotenbergआणिtika: पर्यायी containers. ते फक्त-tikacompose variants मध्ये असतात. हे Office documents (.docx,.xlsx,.odt) चे PDF मध्ये रूपांतर करतात, जेणेकरून paperless त्यांचे indexing करू शकेल.
October 2026 पर्यंत postgres compose फाइल docker.io/library/postgres:18 आणि docker.io/valkey/valkey:9-alpine pin करते आणि app ghcr.io/paperless-ngx/paperless-ngx:latest मधून आणते.
पूर्वतयारी
- sudo प्रवेश असलेला Ubuntu 24.04 KVM VPS आणि Compose plugin सह आधीच स्थापित केलेला Docker. हा भाग नवीन असल्यास, VPS साठी Docker Compose ची मूलतत्त्वे पासून सुरुवात करा आणि नंतर येथे परत या.
- VPS कडे निर्देश करणारा A record असलेले domain name. ज्या hostname बद्दल Paperless ला माहिती दिलेली नाही, त्यावर HTTPS द्वारे sign-in Paperless स्वीकारणार नाही. त्यामुळे हे तुमच्या अपेक्षेपेक्षा आधी आवश्यक ठरते.
- Memory ही मुख्य मर्यादा आहे. PostgreSQL, Valkey, Granian web server आणि Tesseract OCR worker हे सर्व एकाच वेळी memory मध्ये असताना, हलक्या वापरासाठी 2 GB पुरेसे आहेत. शेकडो scans चा backlog import करणार असल्यास 4 GB द्या, कारण मोठ्या multi-page PDF वर OCR चालवताना memory usage अचानक वाढते आणि kernel च्या out-of-memory killer मुळे worker बंद होऊ शकतो.
- Disk: तुमचा archive दोनदा साठवला जातो: मूळ file आणि OCR केलेली archive PDF. त्यामुळे तुमच्या scans च्या आकाराच्या साधारण दुप्पट जागेची तरतूद करा.
अधिकृत 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=1000PAPERLESS_SECRET_KEY मध्ये सुरुवातीला literal value change-me असते. ही key session tokens वर स्वाक्षरी करते. सध्याच्या releases मध्ये हा placeholder unset मानला जातो. key गहाळ, रिकामी किंवा अजूनही change-me असल्यास paperless सुरू होण्यास नकार देते. त्यामुळे ती बदलल्याशिवाय stack सुरू होणार नाही. पहिल्या सुरूवातीपूर्वी ती सेट करा, कारण नंतर ती बदलल्यास प्रत्येक user चे login session संपुष्टात येते.
PAPERLESS_URL हे सेटिंग तुमचा एक तास वाचवते. Paperless हे Django application आहे. Django Host header आणि sign-in form वर browser कळवतो तो origin, दोन्ही तपासते. PAPERLESS_URL सेट केल्यावर ते तुमचा address तुमच्यासाठी ALLOWED_HOSTS, CORS_ALLOWED_HOSTS आणि CSRF_TRUSTED_ORIGINS मध्ये जोडते. ते रिकामे ठेवून एखादा domain या मशीनकडे निर्देशित केल्यास sign-in page तरीही लोड होते, कारण PAPERLESS_ALLOWED_HOSTS ची default value * आहे. परंतु HTTPS द्वारे form submit करताना CSRF verification failed. Request aborted. मुळे अपयश येते, कारण तुमचा domain trusted origin नाही. हे शेवटी slash किंवा path न लावता लिहा.
USERMAP_UID आणि USERMAP_GID container कोणत्या user म्हणून चालते ते ठरवतात. `id -u आणि id -g` ने तपासलेल्या तुमच्या account शी ही values जुळवा. त्या जुळल्या नाहीत, तर तुम्ही consume folder मध्ये copy केलेल्या files consumer ला वाचता येणार नाहीत. त्याऐवजी log मध्ये import न झाल्याचे आणि permission error दिसेल.
stack सुरू करा आणि पहिला वापरकर्ता तयार करा
docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webservercreatesuperuser username, email आणि password विचारते. Default login उपलब्ध नाही. हे पाऊल वगळल्यास वेब इंटरफेस प्रथम उघडणाऱ्या व्यक्तीला superuser तयार करण्यास सांगते. port 8000 अजूनही इंटरनेटसाठी खुला असेल, तर तो वापरकर्ता तुम्हीच असालच असे नाही. त्यामुळे shell मधून लगेच account तयार करा. Browser वापरण्यापूर्वी server port 8000 वर listening करत असल्याचे दर्शविणारी log line येईपर्यंत प्रतीक्षा करा. पहिल्यांदा सुरू होताना database migrations देखील चालतात. यासाठी एक किंवा दोन मिनिटे लागू शकतात.
Domain वापरण्यापूर्वी स्थानिक पातळीवर तपासा:
curl -I http://127.0.0.1:8000302 कडून /accounts/login/ कडे होणारा redirect stack निरोगी असल्याचे दर्शवतो.
यासमोर HTTPS लावा
मूळ compose file मध्ये 8000:8000 प्रकाशित केलेले आहे आणि ते प्रत्येक interface शी bind होते. सार्वजनिक VPS वर यामुळे पत्ता सापडलेल्या कोणालाही तुमचे संपूर्ण document archive plain HTTP द्वारे उपलब्ध होते. Port line बदलून ती फक्त loopback वर bind करा:
ports:
- "127.0.0.1:8000:8000"त्यानंतर reverse proxy मध्ये TLS (transport layer security) समाप्त करा आणि विनंत्या 127.0.0.1:8000 कडे forward करा. या server वर हे एकमेव अॅप असल्यास, ACME (automatic certificate management environment) client असलेला कोणताही proxy वापरता येतो. एका certificate setup मागे अनेक containers चालवत असल्यास, अनेक Docker Compose अॅप्ससाठी Traefik reverse proxy pattern वापरा आणि webserver service ला proxy network शी जोडा; कोणताही published port ठेवू नका.
तुम्ही कोणताही proxy वापरला तरी HTTPS setup मध्ये login form च्या origin check मुळे समस्या निर्माण होतात. PAPERLESS_PROXY_SSL_HEADER सेट केल्याशिवाय Paperless X-Forwarded-Proto कडे दुर्लक्ष करते. त्यामुळे Django प्रत्येक proxied request ला plain HTTP मानते आणि तुमचा browser पाठवणारा https:// origin trusted म्हणून सूचीबद्ध असेल तरच तो स्वीकारला जातो. Browser मध्ये तुम्ही टाइप करता त्या अचूक https:// address वर PAPERLESS_URL सेट केल्याने तो trusted list मध्ये येतो. ते सेट न केल्यास योग्य दिसणाऱ्या page वर CSRF verification failed. Request aborted. मिळते.
Proxy ची upload size limit देखील वाढवा. 1 MB पर्यंत body मर्यादा असलेल्या proxy मधून 40 MB scan पाठवल्यास तो Paperless पर्यंत पोहोचण्यापूर्वीच नाकारला जातो आणि browser generic upload failure दाखवतो.
consume directory कसे कार्य करते
compose file, compose directory मधील ./consume bind-mount करून container मध्ये उपलब्ध करून देते. तुम्ही तेथे ठेवलेली कोणतीही फाइल import केली जाते आणि त्यानंतर त्या folder मधून हटवली जाते, कारण ती फाइल आता paperless च्या व्यवस्थापनाखाली media volume मध्ये साठवली जाते.
cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserverconsumer ने filename उचललेला, OCR चालवलेला आणि document जोडले असल्याचे कळवणाऱ्या ओळीसह प्रक्रिया पूर्ण केलेली दिसली पाहिजे. एक पानाच्या scan साठी ही संपूर्ण प्रक्रिया काही सेकंदांत पूर्ण होते. मोठ्या document साठी तिला एक मिनिट किंवा त्याहून अधिक वेळ लागू शकतो.
फाइल्स कशा शोधल्या जातात हे दोन settings बदलतात. PAPERLESS_CONSUMER_RECURSIVE=true मुळे paperless subfolders मध्ये शोध घेते. PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true मुळे प्रत्येक subfolder चे नाव tag मध्ये रूपांतरित होते. त्यामुळे consume/invoices/2026/ मध्ये फाइल ठेवल्यास तिला invoices आणि 2026 हे tags लागू होतात. तुम्ही तयार करू शकणारी ही सर्वात सोपी filing system आहे.
Detection हा प्रक्रियेचा दुसरा भाग आहे. Default नुसार PAPERLESS_CONSUMER_POLLING_INTERVAL हे 0 असते. याचा अर्थ paperless native filesystem notifications वापरते आणि त्या लगेच trigger होतात. Network filesystem वर ही notifications विश्वसनीय नसतात. तुमचे consume folder NFS किंवा SMB share असल्यास, network scanner त्यात फाइल लिहू शकतो. अशा वेळी फाइल्स detection न होता तेथे पडून राहू शकतात. यावर उपाय म्हणजे interval साठी positive seconds value सेट करणे, जेणेकरून paperless folder scan करेल.
OCR भाषा आणि त्यांचा खर्च
PAPERLESS_OCR_LANGUAGE मध्ये Tesseract चा तीन-अक्षरी कोड द्यावा लागतो. डीफॉल्ट मूल्य eng आहे. deu+eng प्रमाणे अधिक भाषा plus चिन्हाने एकत्र करा. त्यानंतर Tesseract प्रत्येक पानावर सूचीतील सर्व भाषांसह प्रक्रिया करते. त्यामुळे प्रत्येक अतिरिक्त भाषेमुळे प्रत्येक scan साठी CPU वेळ वाढतो. shared-vCPU VPS वर यामुळे scan दहा सेकंदांत पूर्ण होण्याऐवजी एक मिनिट लागू शकतो. तुमची कागदपत्रे प्रत्यक्षात ज्या भाषांमध्ये लिहिलेली आहेत, फक्त त्याच भाषा सूचीबद्ध करा.
या image मध्ये English, German, Italian, Spanish आणि French भाषा समाविष्ट आहेत. इतर कोणत्याही भाषेसाठी ती भाषा PAPERLESS_OCR_LANGUAGES मध्ये space-separated list म्हणून जोडा. उदाहरणार्थ, PAPERLESS_OCR_LANGUAGES=tur ces. त्यानंतर restart करा. container startup वेळी Tesseract data packs download करते. त्यामुळे हा बदल केल्यानंतरचा पहिला boot अधिक वेळ घेतो.
डेटाबेस आणि media चा बॅकअप घ्या
PostgreSQL चालू असताना Docker volumes कॉपी केल्यास असा बॅकअप तयार होऊ शकतो जो restore करता येणार नाही. Paperless मध्ये स्वतःचा exporter उपलब्ध आहे. तो documents आणि सर्व metadata चा JSON manifest ./export bind mount मध्ये लिहितो:
docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar--delete सध्याच्या document शी जुळत नसलेल्या exported files काढून टाकते. त्यामुळे folder सतत वाढत न राहता mirror प्रमाणे राहतो. --no-progress-bar हे cron मधून चालवल्यावर output स्वच्छ ठेवते. -T मुळे Compose अशा terminal ची मागणी करत नाही जो cron कडे उपलब्ध नसतो.
नवीन stack वर त्याच folder मधून restore करणे document_importer आहे. त्यामुळे सुरक्षित ठेवायची एकमेव गोष्ट म्हणजे export directory. तो ठरावीक वेळापत्रकानुसार तुमच्या VPS वरील encrypted, deduplicated restic backups द्वारे offsite पाठवा. restic ने अर्धवट लिहिलेला archive capture करू नये यासाठी आधी export चालवा.
export/manifest.json अस्तित्वात आहे आणि file count interface मधील document count शी जुळते हे तपासून बॅकअपची पडताळणी करा. तुम्ही कधीही सूची तपासलेली नाही असा बॅकअप म्हणजे बॅकअप नाही. रात्रीचा export शांतपणे fail होऊ लागणे याहूनही गंभीर आहे. त्यामुळे cron job ने त्याचा exit status तुमच्या स्वतःच्या ntfy server कडे पाठवावा. मग restore ची गरज भासेपर्यंत थांबण्याऐवजी तो fail झालेल्या आठवड्यातच तुम्हाला कळेल.
FAQ
माझ्या domain कडे निर्देश केल्यानंतर प्रत्येक पृष्ठावर "Bad Request (400)" का दिसते?
मूळ files वापरल्यास असे होऊ नये, कारण PAPERLESS_ALLOWED_HOSTS ची default value * असते. Container log मध्ये DisallowedHost असलेला 400 म्हणजे PAPERLESS_ALLOWED_HOSTS मध्ये तुमचा domain वगळणारी list सेट केली आहे. docker-compose.env मध्ये PAPERLESS_URL=https://paperless.example.com सेट करा; शेवटी slash देऊ नका. त्यामुळे paperless हा hostname list मध्ये जोडेल. किंवा PAPERLESS_ALLOWED_HOSTS ची line काढून टाका. त्यानंतर container पुन्हा तयार करण्यासाठी docker compose up -d चालवा. फक्त env file edit केल्याने काही होत नाही, कारण चालू container सुरू होताना मिळालेले environment वापरत राहतो.
consume folder मध्ये PDF ठेवला, पण काहीच झाले नाही. समस्या काय आहे?
प्रथम docker compose logs webserver तपासा. Permission error म्हणजे USERMAP_UID आणि USERMAP_GID हे file च्या मालकीच्या account शी जुळत नाहीत. त्यामुळे त्या दुरुस्त करून container पुन्हा तयार करा. Log मध्ये एकही line नसल्यास file event पोहोचलेला नाही. Network shares वर native filesystem notifications विश्वसनीय नसल्यामुळे असे होते. PAPERLESS_CONSUMER_POLLING_INTERVAL ची value 30 सारखी सेट करा. त्यानंतर paperless प्रत्येक 30 सेकंदांनी folder scan करेल.
PostgreSQL ऐवजी SQLite वापरून paperless-ngx चालवता येईल का?
होय. docker-compose.sqlite.yml समर्थित आहे आणि ते कमी memory वापरते, त्यामुळे लहान VPS साठी योग्य आहे. Archive वाढल्यानंतर त्याची मर्यादा दिसते. हजारो documents झाल्यावर full-text search आणि bulk tag edits लक्षणीयरीत्या धीमे होतात. नंतर migration करण्यासाठी export आणि import करावे लागतात. त्यामुळे archive सतत वाढणार असेल, तर आता PostgreSQL निवडा.
Scans च्या archive साठी प्रत्यक्षात किती disk space आवश्यक आहे?
तुमच्या source files च्या आकाराच्या साधारण दुप्पट. Paperless मूळ file मध्ये बदल करत नाही. ते searchable text layer असलेली दुसरी OCR केलेली PDF आणि काही लहान thumbnails साठवते. 200 KB ची text-only scan लहानच राहते. दीर्घ contract ची 30 MB colour scan सुमारे 60 MB जागा घेते. Export directory त्याच disk वर ठेवत असल्यास तिची जागाही जोडा. त्यामुळे त्याच archive साठी disk वर एकूण सुमारे तीनपट जागा लागते.
Tika आणि Gotenberg containers आवश्यक आहेत का?
तुमच्या PDFs सोबत Word, Excel किंवा OpenDocument files index करायच्या असतील, तरच. Paperless त्या formats चे PDF मध्ये रूपांतर करते, जेणेकरून त्यांच्यावर OCR आणि search करता येईल. या containers मुळे आणखी दोन running containers आणि काही शेकडो megabytes memory लागतात. तुम्ही साठवत असलेल्या सर्व files आधीपासून PDF किंवा image असतील, तर लहान server वर हे containers टाळा.