VPSలో Paperless-ngxను ఇన్స్టాల్ చేయడం ఎలా?
Docker Compose ఉపయోగించి VPSలో Paperless-ngxను ఎలా సెటప్ చేయాలో తెలుసుకోండి. Postgres డేటాబేస్, OCR లాంగ్వేజెస్, HTTPS కాన్ఫిగరేషన్ మరియు డేటా బ్యాకప్ వంటి ముఖ్యమైన అంశాల వివరణ.
మీరు నిర్మించేది
VPSపై Paperless-ngx అమలు చేస్తే, స్కాన్ చేసిన కాగితాలను searchable archiveగా మార్చవచ్చు. మీరు PDFను పర్యవేక్షించే directoryలో ఉంచితే, server దానిపై OCR (optical character recognition) అమలు చేసి, textను extract చేసి, date మరియు correspondentను అంచనా వేసి, దాన్ని archive చేస్తుంది. Installationలో నాలుగు services కలిగిన ఒక Docker Compose file మాత్రమే ఉంటుంది. ఆ తర్వాతి పని మొత్తం configurationకు సంబంధించినదే. Installలు ఎక్కువగా విఫలమయ్యేది అక్కడే కాబట్టి, ఈ guideలో ఎక్కువ భాగం దానిపైనే ఉంటుంది. ఇది photo library కాదు. OCR మరియు correspondent guessing holiday JPEGల directoryపై ఉపయోగపడవు. అందువల్ల వాటిని వాటి కోసం రూపొందించిన photo serverలో ఉంచి, paperlessను కాగితాల కోసం మాత్రమే ఉపయోగించండి. Video విషయంలోనూ ఇదే వర్తిస్తుంది. Ripped films collection media serverలో ఉండాలి. అక్కడ 90s rental storeలా కనిపించే Jellyfin front end browsingను ప్రధాన ఉద్దేశ్యంగా చేస్తుంది, searchingను కాదు.
Paperless-ngx అనేది అసలు Paperless projectకు community నిర్వహిస్తున్న fork. ఇది free, self-hosted, మరియు మీ documentsను diskపై plain filesగా నిల్వ చేస్తుంది. కాబట్టి మీ స్వంత archiveకు మీరు ఎప్పటికీ ప్రాప్యత కోల్పోరు. Home boxకు బదులుగా VPSపై దీన్ని అమలు చేస్తే, home routerలో port తెరవకుండానే scansను ఎక్కడి నుంచైనా access చేయవచ్చు. అలాగే, paper కాని files కోసం private Nextcloud instanceతో ఇది బాగా పనిచేస్తుంది. మీ scanner plug చేసిన desktopకూ ఇదే విధానం వర్తిస్తుంది. ఎందుకంటే ఆ VPSలో మీ స్వంత RustDesk relay ఉంటే, routerలో hole తెరవకుండానే ఆ machineను వేరే ప్రదేశం నుంచి నియంత్రించవచ్చు.
స్టాక్ వాస్తవంగా ఏవి నడుపుతుంది
అధికారిక compose file నాలుగు 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-compatible key-value store. ఇది web process మరియు workers మధ్య task queue గా పనిచేస్తుంది.gotenbergమరియుtika: ఐచ్ఛికమైనవి. ఇవి-tikacompose variants లో మాత్రమే ఉంటాయి. ఇవి Office documents (.docx,.xlsx,.odt) ను PDF గా మార్చి, paperless వాటిని index చేయగలిగేలా చేస్తాయి.
October 2026 నాటికి postgres compose file docker.io/library/postgres:18 మరియు docker.io/valkey/valkey:9-alpine ను నిర్దిష్టంగా ఉపయోగిస్తుంది. ఇది app ను ghcr.io/paperless-ngx/paperless-ngx:latest నుంచి pull చేస్తుంది.
ముందస్తు అవసరాలు
- sudo యాక్సెస్ ఉన్న Ubuntu 24.04 KVM VPS, అలాగే Compose plugin ఇప్పటికే ఇన్స్టాల్ చేసిన Docker. ఈ భాగం మీకు కొత్త అయితే, ముందుగా VPS కోసం Docker Compose ప్రాథమికాలు చదివి, తరువాత ఇక్కడికి తిరిగి రండి.
- VPS వైపు చూపించే A record ఉన్న domain name. తనకు తెలియజేయని hostname పై HTTPS ద్వారా sign-in ను Paperless అంగీకరించదు. అందువల్ల ఇది మీరు ఊహించినదానికంటే ముందుగానే సిద్ధం చేయాలి.
- ప్రధాన పరిమితి memory. PostgreSQL, Valkey, Granian web server మరియు Tesseract OCR worker ఒకేసారి memoryలో ఉండే light use కోసం 2 GB సరిపోతుంది. వందల scanలను backlogగా import చేయాలనుకుంటే 4 GB కేటాయించండి. పెద్ద multi-page PDFపై OCR నడిచినప్పుడు memory వినియోగం ఒక్కసారిగా పెరిగి, kernel out-of-memory killer workerను నిలిపివేయవచ్చు.
- Disk: మీ archive రెండుసార్లు నిల్వ అవుతుంది: original file మరియు OCR చేసిన archive PDF. కాబట్టి మీ scanల పరిమాణానికి సుమారు రెట్టింపు disk space కేటాయించండి.
అధికారిక 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 తో పోలిస్తే full-text search ఇండెక్స్ త్వరగా నెమ్మదిస్తుంది.
.env ఫైల్ ఒకే లైన్ను కలిగి ఉంటుంది, అదే COMPOSE_PROJECT_NAME=paperless. ఆ పేరు ప్రతి కంటైనర్ మరియు వాల్యూమ్కు ప్రిఫిక్స్గా మారుతుంది, కాబట్టి దాన్ని తొలగించి, ఆ తర్వాత docker compose down -v మీ డేటాను ఎందుకు కనుగొనలేకపోతుందో అని ఆశ్చర్యపోకండి.
మొదటి ప్రారంభానికి ముందు docker-compose.env ను configure చేయండి
రెండు settings తప్పనిసరి. Project documentationలో ఇచ్చిన commandతో secret keyని generate చేయండి:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"తర్వాత docker-compose.env ను edit చేయండి:
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 లో అక్షరాలా change-me value ఉంటుంది. ఇది session tokensపై సంతకం చేస్తుంది. ప్రస్తుత releases ఆ placeholderను unsetగా పరిగణిస్తాయి. Key missingగా, blankగా లేదా ఇంకా change-me గా ఉంటే paperless ప్రారంభం కావడానికి నిరాకరిస్తుంది. అందువల్ల దాన్ని replace చేసే వరకు stack ప్రారంభం కాదు. మొదటి startకు ముందే దీన్ని set చేయండి. తర్వాత మార్చితే ప్రతి user logout అవుతారు.
PAPERLESS_URL మీకు ఒక గంట సమయాన్ని ఆదా చేసే setting. Paperless ఒక Django application. Django Host headerను, sign-in formలో browser పంపే originను కూడా తనిఖీ చేస్తుంది. PAPERLESS_URL ను set చేస్తే, అది మీ addressను స్వయంచాలకంగా ALLOWED_HOSTS, CORS_ALLOWED_HOSTS మరియు CSRF_TRUSTED_ORIGINS లోకి చేర్చుతుంది. దీన్ని ఖాళీగా వదిలి, machineకు domain point చేసినా sign-in page load అవుతుంది. కారణం, PAPERLESS_ALLOWED_HOSTS defaultగా * గా ఉంటుంది. కానీ HTTPS ద్వారా form submit చేయడం CSRF verification failed. Request aborted. తో విఫలమవుతుంది. ఎందుకంటే మీ domain trusted origin కాదు. దీన్ని trailing slash లేదా path లేకుండా రాయండి.
Container ఏ userగా నడవాలో USERMAP_UID మరియు USERMAP_GID నిర్దేశిస్తాయి. id -u మరియు id -g తో తనిఖీ చేసిన మీ స్వంత accountకు ఇవి సరిపోలాలి. అవి సరిపోలకపోతే, మీరు consume folderలోకి copy చేసే filesను consumer చదవలేడు. అప్పుడు import జరగకుండా logలో permission error కనిపిస్తుంది.
స్టాక్ను ప్రారంభించి మొదటి వినియోగదారుని సృష్టించండి
docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webservercreatesuperuser వినియోగదారు పేరు, email మరియు password కోసం prompts చూపిస్తుంది. Default login ఉండదు. ఈ దశను దాటేస్తే, web interface ను మొదట తెరిచే వ్యక్తిని superuser సృష్టించమని అడుగుతుంది. port 8000 ఇప్పటికీ internet కు తెరిచి ఉంటే, ఆ వ్యక్తి మీరే కాకపోవచ్చు. అందువల్ల shell నుంచి వెంటనే account సృష్టించండి. Browser ను తెరవడానికి ముందు server port 8000 పై listening చేస్తున్నట్లు తెలిపే log line వచ్చే వరకు వేచి ఉండండి. మొదటి start సమయంలో database migrations కూడా అమలవుతాయి. దీనికి ఒకటి లేదా రెండు నిమిషాలు పడుతుంది.
Domain ను ఉపయోగించే ముందు locally తనిఖీ చేయండి:
curl -I http://127.0.0.1:8000302 నుంచి /accounts/login/ కు redirect కనిపిస్తే stack సక్రమంగా పనిచేస్తున్నట్లు అర్థం.
దాని ముందు HTTPS ఉంచండి
డిఫాల్ట్ compose file 8000:8000 ను publish చేస్తుంది. ఇది ప్రతి interface కు bind అవుతుంది. Public VPSలో address కనుగొన్న ఎవరైనా మీ పూర్తి document archive ను plain HTTP ద్వారా చూడగలరు. Port line ను loopback కు మాత్రమే bind అయ్యేలా మార్చండి:
ports:
- "127.0.0.1:8000:8000"తర్వాత reverse proxyలో TLS (transport layer security) termination చేసి, requests ను 127.0.0.1:8000 కు forward చేయండి. ఈ machineలో ఇదొక్కటే app అయితే, ACME (automatic certificate management environment) client కలిగిన ఏ proxy అయినా సరిపోతుంది. ఒకే certificate setup వెనుక అనేక containers నడుపుతున్నట్లయితే, అనేక Docker Compose apps కోసం Traefik reverse proxy విధానం ను అనుసరించండి. Published port లేకుండా webserver service ను proxy networkకు attach చేయండి.
మీరు ఉపయోగించే proxy ఏదైనా కావచ్చు. అయితే HTTPS setupలు login form యొక్క origin check వద్ద విఫలమవుతాయి. PAPERLESS_PROXY_SSL_HEADER ను set చేయకపోతే Paperless X-Forwarded-Proto ను పట్టించుకోదు. ఇది defaultగా offలో ఉంటుంది. అందువల్ల Django ప్రతి proxied requestను plain HTTPగా పరిగణిస్తుంది. మీ browser పంపే https:// origin, trustedగా జాబితా చేయబడితేనే pass అవుతుంది. మీరు browserలో type చేసే ఖచ్చితమైన https:// addressకు PAPERLESS_URL ను set చేస్తే అది ఆ జాబితాలో చేరుతుంది. ఇది లేకపోతే సరిగ్గా కనిపించే pageలో CSRF verification failed. Request aborted. కనిపిస్తుంది.
Proxy యొక్క upload size limitను కూడా పెంచండి. 1 MBకు bodiesను పరిమితం చేసే proxy ద్వారా 40 MB scan పంపితే, paperless దాన్ని స్వీకరించకముందే request reject అవుతుంది. Browser సాధారణ upload failureను చూపిస్తుంది.
consume directory ఎలా పనిచేస్తుంది
compose file, compose directory లోని ./consume ను container లోకి bind-mount చేస్తుంది. మీరు అక్కడ ఉంచే ఏదైనా file import అయిన తర్వాత ఆ folder నుంచి తొలగించబడుతుంది. ఎందుకంటే ఆ file paperless నిర్వహణలోని media volume లో ఉంటుంది.
cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserverconsumer filename ను గుర్తించి, OCR అమలు చేసి, document జోడించబడిందని తెలిపే line తో ప్రక్రియ పూర్తిచేయాలి. ఒక పేజీ scan కు మొత్తం cycle కొన్ని seconds పడుతుంది. పెద్ద document కు minute లేదా అంతకంటే ఎక్కువ సమయం పట్టవచ్చు.
Files ఎలా కనుగొనాలో రెండు settings మారుస్తాయి. PAPERLESS_CONSUMER_RECURSIVE=true వల్ల paperless subfolders లో కూడా వెతుకుతుంది. PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true వల్ల ప్రతి subfolder పేరు tag గా మారుతుంది. అందువల్ల file ను consume/invoices/2026/ లో ఉంచితే, దానికి invoices మరియు 2026 tags వర్తిస్తాయి. మీరు నిర్మించగల అత్యంత సరళమైన filing system ఇదే.
Detection ప్రక్రియలో మరో భాగం. Default గా PAPERLESS_CONSUMER_POLLING_INTERVAL విలువ 0 గా ఉంటుంది. అంటే paperless native filesystem notifications ను ఉపయోగిస్తుంది. ఇవి వెంటనే trigger అవుతాయి. Network filesystem పై ఈ notifications నమ్మదగినవి కావు. Network scanner అందులో write చేయడానికి మీ consume folder NFS లేదా SMB share అయితే, files గుర్తించబడకుండా అక్కడే ఉండిపోవచ్చు. దీనికి పరిష్కారం interval ను positive number of seconds గా సెట్ చేయడం. అప్పుడు paperless notifications పై ఆధారపడకుండా folder ను scan చేస్తుంది.
OCR భాషలు మరియు వాటి వ్యయం
PAPERLESS_OCR_LANGUAGE లో మూడు అక్షరాల Tesseract code ఇవ్వాలి. డిఫాల్ట్ విలువ eng. deu+eng వలె plus sign తో భాషలను కలపండి. ఆపై Tesseract ప్రతి పేజీలో జాబితా చేసిన అన్ని భాషలతో పనిచేస్తుంది. అందువల్ల ప్రతి అదనపు భాష ప్రతి scan కు CPU సమయాన్ని పెంచుతుంది. Shared-vCPU VPS లో దీని వల్ల scan పది seconds లో పూర్తవడం, ఒక minute పట్టడం మధ్య తేడా రావచ్చు. మీ documents వాస్తవంగా ఏ భాషల్లో రాయబడ్డాయో ఆ భాషలను మాత్రమే జాబితా చేయండి.
ఈ image లో English, German, Italian, Spanish మరియు French అందుబాటులో ఉంటాయి. ఇతర భాష కోసం, PAPERLESS_OCR_LANGUAGES కు space-separated list గా ఆ భాషను జోడించండి. ఉదాహరణకు PAPERLESS_OCR_LANGUAGES=tur ces. తరువాత restart చేయండి. Container ప్రారంభ సమయంలో Tesseract data packs ను download చేస్తుంది. అందువల్ల ఆ మార్పు చేసిన తర్వాత మొదటి boot కు ఎక్కువ సమయం పడుతుంది.
డేటాబేస్ మరియు మీడియాను బ్యాకప్ చేయండి
PostgreSQL నడుస్తున్నప్పుడు Docker volumes ను కాపీ చేస్తే, restore చేయలేని బ్యాకప్ లభించవచ్చు. Paperless తన సొంత exporter ను అందిస్తుంది. ఇది పత్రాలతో పాటు మొత్తం metadata కు సంబంధించిన JSON manifest ను ./export bind mount లో రాస్తుంది:
docker compose exec -T webserver document_exporter ../export --delete --no-progress-barప్రస్తుత పత్రంతో ఇక సరిపోలని exported files ను --delete తొలగిస్తుంది. అందువల్ల folder ఎప్పటికీ పెరుగుతూ ఉండకుండా mirror గా ఉంటుంది. cron నుంచి ఇది నడిచేటప్పుడు output ను శుభ్రంగా ఉంచేందుకు --no-progress-bar ఉపయోగించండి. cron వద్ద లేని terminal కోసం Compose అడగకుండా -T నిరోధిస్తుంది.
కొత్త stack పై అదే folder నుంచి restore చేయడం document_importer. అంటే మీరు భద్రంగా ఉంచాల్సింది export directory మాత్రమే. మీ VPS నుంచి encrypted, deduplicated restic backups ఉపయోగించి నిర్ణీత షెడ్యూల్లో దానిని offsite కు పంపండి. ముందుగా export ను అమలు చేయండి. అప్పుడు restic సగం రాసిన archive ను ఎప్పుడూ capture చేయదు.
export/manifest.json ఉందో లేదో తనిఖీ చేసి, file count interface లోని మీ document count తో సరిపోతుందో చూసి బ్యాకప్ను ధృవీకరించండి. మీరు ఎప్పుడూ జాబితా చేయని బ్యాకప్ నిజమైన బ్యాకప్ కాదు. ప్రతి రాత్రి జరిగే export నిశ్శబ్దంగా విఫలమవడం ఇంకా ప్రమాదకరం. అందువల్ల cron job తన exit status ను మీ స్వంత ntfy server కు పంపేలా చేయండి. అప్పుడు restore అవసరమైన రోజున కాకుండా, అది విఫలమైన వారంలోనే మీకు తెలుస్తుంది.
FAQ
నా domain ను దీనికి చూపించిన తర్వాత ప్రతి page "Bad Request (400)" ఎందుకు చూపిస్తోంది?
ప్రామాణిక files తో ఇలా జరగకూడదు, ఎందుకంటే PAPERLESS_ALLOWED_HOSTS యొక్క default విలువ *. Container log లో DisallowedHost తో కూడిన 400 కనిపిస్తే, PAPERLESS_ALLOWED_HOSTS లో మీ domain లేని list సెట్ అయిందని అర్థం. docker-compose.env లో, చివర slash లేకుండా, PAPERLESS_URL=https://paperless.example.com ను సెట్ చేయండి. అప్పుడు paperless ఆ hostname ను list కు జోడిస్తుంది. లేదా PAPERLESS_ALLOWED_HOSTS line ను తొలగించండి. తరువాత container ను మళ్లీ సృష్టించడానికి docker compose up -d ను అమలు చేయండి. Env file ను మాత్రమే సవరించడం వల్ల ప్రయోజనం ఉండదు. ఎందుకంటే నడుస్తున్న container ప్రారంభమైనప్పుడు పొందిన environment నే ఉపయోగిస్తుంది.
consume folder లో PDF ఉంచినా ఏమీ జరగలేదు. సమస్య ఏమిటి?
ముందుగా docker compose logs webserver ను పరిశీలించండి. Permission error కనిపిస్తే, USERMAP_UID మరియు USERMAP_GID file కు owner అయిన account తో సరిపోలడం లేదని అర్థం. వాటిని సరిచేసి container ను మళ్లీ సృష్టించండి. Log లో ఎలాంటి line కనిపించకపోతే file event అసలు చేరలేదని అర్థం. Native filesystem notifications అక్కడ విశ్వసనీయంగా ఉండవు కాబట్టి network shares పై ఇది జరుగుతుంది. PAPERLESS_CONSUMER_POLLING_INTERVAL ను 30 వంటి విలువకు సెట్ చేయండి. అప్పుడు paperless ప్రతి 30 సెకన్లకు folder ను scan చేస్తుంది.
PostgreSQL బదులు SQLite తో paperless-ngx ను నడపవచ్చా?
అవును. docker-compose.sqlite.yml కు మద్దతు ఉంది. ఇది తక్కువ memory ఉపయోగిస్తుంది కాబట్టి చిన్న VPS కు సరిపోతుంది. Archive పెరిగే కొద్దీ దీని పరిమితి కనిపిస్తుంది. వేల సంఖ్యలో documents ఉన్నప్పుడు full-text search మరియు bulk tag edits గమనించదగినంత నెమ్మదిస్తాయి. తరువాత migrate చేయాలంటే export మరియు import అవసరం. Archive నిరంతరం పెరుగుతుందని మీరు భావిస్తే, ఇప్పుడే PostgreSQL ఎంచుకోండి.
Scans archive కు వాస్తవంగా ఎంత disk అవసరం?
సాధారణంగా source files పరిమాణానికి దాదాపు రెండింతలు అవసరం. Paperless అసలు file ను మార్పు లేకుండా ఉంచుతుంది. Search చేయగల text layer ఉన్న రెండవ OCR'd PDF తో పాటు చిన్న thumbnails ను కూడా నిల్వ చేస్తుంది. Text మాత్రమే ఉన్న 200 KB scan చిన్న పరిమాణంలోనే ఉంటుంది. పొడవైన contract యొక్క 30 MB colour scan సుమారు 60 MB నిల్వ చేస్తుంది. Export directory ను అదే disk లో ఉంచితే దాని పరిమాణాన్ని కూడా కలపండి. అప్పుడు అదే archive disk పై మూడు రెట్లు స్థలాన్ని ఉపయోగిస్తుంది.
Tika మరియు Gotenberg containers అవసరమా?
మీ PDFs తో పాటు Word, Excel లేదా OpenDocument files ను index చేయాలనుకుంటే మాత్రమే అవసరం. Paperless వాటిని PDF గా convert చేసి OCR చేసి search చేయగలిగేలా చేస్తుంది. ఇవి మరో రెండు running containers ను, కొన్ని వందల megabytes memory ను జోడిస్తాయి. మీరు file చేసే ప్రతిదీ ఇప్పటికే PDF లేదా image అయితే చిన్న server లో వీటిని వదిలేయండి.