SSD Nodes Learn Hosting plans →
Mwongozo Matt ConnorNa Matt Connor · Imeboreshwa 2026-10-25

Jinsi ya kusakinisha Paperless-ngx kwenye VPS

Jifunze kusakinisha Paperless-ngx kwenye VPS kwa kutumia Docker Compose. Mwongozo huu unaelezea usanidi wa Postgres, PAPERLESS_URL, OCR, HTTPS, na mbinu bora za kuhifadhi nakala.

Unachojenga

Paperless-ngx kwenye VPS hubadilisha folda ya karatasi zilizochanganuliwa kuwa kumbukumbu inayoweza kutafutwa. Unaweka PDF kwenye directory inayofuatiliwa, kisha seva huiendeshea OCR (optical character recognition), hutoa maandishi, hukisia tarehe na mhusika wa mawasiliano, halafu huihifadhi. Usakinishaji unatumia faili moja ya Docker Compose yenye huduma nne. Baada ya hapo, kila kitu ni usanidi. Mwongozo huu una sehemu kubwa kuhusu usanidi kwa sababu hapo ndipo usakinishaji hushindwa. Paperless-ngx si maktaba ya picha: OCR na ukisiaji wa mhusika wa mawasiliano havisaidii kwenye folda ya JPEG za likizo. Kwa hiyo, ziweke kwenye seva ya picha iliyoundwa kwa ajili yake na uitumie Paperless kwa nyaraka za karatasi. Video ina kanuni hiyo hiyo: rafu ya filamu zilizoripuliwa inafaa kuwa kwenye media server, ambapo kitu kama frontend ya Jellyfin iliyoundwa kama duka la kukodisha la miaka ya 90 huifanya kuvinjari kuwa lengo badala ya kutafuta.

Paperless-ngx ni fork ya jumuiya inayodumishwa ya mradi wa awali wa Paperless. Ni programu isiyolipishwa, unayojihifadhi mwenyewe, na huhifadhi nyaraka zako kama faili za kawaida kwenye diski. Kwa hiyo, huwezi kuzuiwa kufikia kumbukumbu yako mwenyewe. Kuiendesha kwenye VPS badala ya kompyuta ya nyumbani kunamaanisha kwamba unaweza kufikia scans zako kutoka mahali popote bila kufungua port kwenye router ya nyumbani. Pia inaendana vizuri na instance ya kibinafsi ya Nextcloud kwa faili ambazo si za karatasi. Mantiki hiyo hiyo inahusu desktop ambayo scanner yako imeunganishwa nayo, kwa sababu relay yako mwenyewe ya RustDesk kwenye VPS hiyo hukuruhusu kuendesha mashine hiyo ukiwa mbali bila kufungua mwanya kwenye router.

Stack inayotumika kwa kweli

Faili rasmi ya compose huanzisha containers nne. Kujua kazi ya kila moja hufanya logs ziwe rahisi kuelewa.

  • webserver: image ya paperless-ngx yenyewe. Huendesha kiolesura cha web, API, consumer anayefuatilia input folder yako, pamoja na Celery task workers wanaofanya OCR.
  • db: PostgreSQL. Huhifadhi metadata, tags, correspondents na jedwali za full-text search index. Haihifadhi PDFs zako.
  • broker: Valkey, key-value store inayooana na Redis. Ni task queue kati ya web process na workers.
  • gotenberg na tika: ni za hiari, na hutumika tu katika compose variants za -tika. Hubadilisha documents za Office (.docx, .xlsx, .odt) kuwa PDF ili paperless iweze kuzi-index.

Kufikia October 2026, faili ya postgres compose inafunga docker.io/library/postgres:18 na docker.io/valkey/valkey:9-alpine kwenye matoleo maalum, na hupakua app kutoka ghcr.io/paperless-ngx/paperless-ngx:latest.

Masharti ya awali

  • Ubuntu 24.04 KVM VPS yenye ufikiaji wa sudo, pamoja na Docker iliyo na Compose plugin iliyosakinishwa tayari. Ikiwa sehemu hii ni mpya kwako, anza na msingi wa Docker Compose kwa VPS kisha urudi hapa.
  • Jina la domain lenye A record inayoelekeza kwenye VPS. Paperless haitakubali kuingia kupitia HTTPS kwa hostname ambayo haijaelezwa ndani ya usanidi wake, kwa hiyo hili ni muhimu mapema kuliko unavyotarajia.
  • Kumbukumbu ndiyo kikwazo kikuu. PostgreSQL, Valkey, web server ya Granian na worker mmoja wa Tesseract OCR zinaweza kukaa kwa wakati mmoja ndani ya 2 GB kwa matumizi mepesi. Tenga 4 GB ikiwa unapanga kuingiza foleni ya mamia ya scans, kwa sababu OCR ya PDF kubwa yenye kurasa nyingi ndiyo ongezeko la matumizi ya kumbukumbu linaloweza kusababisha kernel kumuua worker kwa sababu ya kuishiwa kumbukumbu.
  • Disk: archive yako huhifadhiwa mara mbili: faili asili na archive PDF iliyofanyiwa OCR. Kwa hiyo, panga nafasi inayokadiriwa kuwa mara mbili ya ukubwa wa scans zako.

Pata faili rasmi za compose

Kuna kisakinishi shirikishi:

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

Hukuuliza maswali na kukuandikia faili hizo. Kufanya hivyo kwa mikono kunahusisha amri nne na kukuacha ukiwa unajua kila kitu kilipo, jambo ambalo ni muhimu kwenye seva utakayoisimamia.

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

Tofauti za faili hizo zipo kwenye saraka moja: docker-compose.sqlite.yml, docker-compose.mariadb.yml, na toleo la -tika la kila moja. Chagua postgres kwa usakinishaji mpya. SQLite inafaa kwa hati chache mia kadhaa, lakini index ya utafutaji wa maandishi kamili (full-text search) huwa polepole muda mrefu kabla ya PostgreSQL.

Faili ya .env ina mstari mmoja, COMPOSE_PROJECT_NAME=paperless. Jina hilo huwa kiambishi awali (prefix) kwenye kila container na volume, kwa hivyo usilifute kisha ukashangaa kwa nini docker compose down -v haiwezi kupata data zako.

Sanidi docker-compose.env kabla ya kuwasha mara ya kwanza

Mipangilio miwili si ya hiari. Tengeneza secret key kwa kutumia command iliyoandikwa kwenye nyaraka za project:

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

Kisha hariri 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 hutolewa ikiwa na value halisi change-me. Hutia saini session tokens, na releases za sasa huchukulia placeholder hiyo kuwa haijawekwa: paperless hukataa kuanza ikiwa key haipo, ni tupu au bado ni change-me. Kwa hiyo stack haitawaka hadi uibadilishe. Iweke kabla ya kuwasha mara ya kwanza, kwa sababu kuibadilisha baadaye huwatoa watumiaji wote kwenye akaunti zao.

PAPERLESS_URL ndiyo mipangilio inayookoa saa moja ya utatuzi. Paperless ni Django application, na Django hukagua header ya Host pamoja na origin ambayo browser huripoti kwenye sign-in form. Ukiweka PAPERLESS_URL, inaongeza address yako kwenye ALLOWED_HOSTS, CORS_ALLOWED_HOSTS na CSRF_TRUSTED_ORIGINS kwa ajili yako. Ukiiacha tupu na kuelekeza domain kwenye server, sign-in page bado hupakia kwa sababu PAPERLESS_ALLOWED_HOSTS huwa na thamani ya kawaida *. Hata hivyo, kuituma kupitia HTTPS hushindikana kwa CSRF verification failed. Request aborted. kwa sababu domain yako si trusted origin. Iandike bila trailing slash wala path.

USERMAP_UID na USERMAP_GID huweka user ambaye container huendesha kama. Zilinganishe na account yako mwenyewe, iliyothibitishwa kwa id -u na id -g. Zisipolingana, files unazonakili kwenye consume folder hazitasomeka na consumer, na log itaonyesha permission error badala ya import.

Washa stack na uunde mtumiaji wa kwanza

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

createsuperuser hukuuliza jina la mtumiaji, barua pepe na nenosiri. Hakuna login ya chaguo-msingi. Ukiruka hatua hii, kiolesura cha wavuti humwomba mtu wa kwanza anayekifungua aunde superuser. Ikiwa port 8000 bado iko wazi kwenye Internet, huenda mtu huyo asiwe wewe. Kwa hiyo, unda akaunti kutoka kwenye shell mara moja. Subiri mstari wa log unaoripoti kwamba server inasikiliza kwenye port 8000 kabla ya kujaribu kivinjari. Kuwasha kwa mara ya kwanza pia huendesha database migrations, jambo linalochukua dakika moja au mbili.

Ihakiki kwenye mashine ya ndani kabla ya kutumia domain:

curl -I http://127.0.0.1:8000

302 redirect kwenda /accounts/login/ inamaanisha stack iko katika hali nzuri.

Weka HTTPS mbele ya huduma

Faili ya kawaida ya Compose huchapisha 8000:8000, ambayo hufungamana na kila interface. Kwenye VPS ya umma, hali hii huweka kumbukumbu yako yote ya nyaraka wazi kupitia HTTP isiyosimbwa kwa mtu yeyote anayepata anwani hiyo. Badilisha mstari wa port ili ufungamane na loopback pekee:

    ports:
      - "127.0.0.1:8000:8000"

Kisha tekeleza TLS (transport layer security) kwenye reverse proxy na uelekeze maombi kwenye 127.0.0.1:8000. Ikiwa hii ndiyo app pekee kwenye seva, proxy yoyote yenye client ya ACME (automatic certificate management environment) itatosha. Ikiwa unaendesha containers kadhaa nyuma ya usanidi mmoja wa certificate, fuata muundo wa Traefik reverse proxy kwa apps nyingi za Docker Compose na uunganishe huduma ya webserver kwenye mtandao wa proxy bila kuchapisha port kabisa.

Bila kujali proxy unayotumia, ukaguzi wa origin wa fomu ya kuingia ndiyo sehemu ambayo usanidi wa HTTPS huvurugika. Paperless hupuuza X-Forwarded-Proto isipokuwa uweke PAPERLESS_PROXY_SSL_HEADER, ambayo imezimwa kwa chaguo-msingi. Kwa hiyo, Django huchukulia kila ombi lililopitishwa na proxy kuwa HTTP isiyosimbwa, na origin ya https:// ambayo browser yako hutuma hupita tu ikiwa imeorodheshwa kuwa trusted. Kuweka PAPERLESS_URL kwenye anwani halisi ya https:// unayoandika kwenye browser ndiko kunakoiweka kwenye orodha hiyo. Bila hilo, utapata CSRF verification failed. Request aborted. kwenye ukurasa unaoonekana kuwa sahihi.

Pia ongeza kikomo cha ukubwa wa upload kwenye proxy. Scan ya 40 MB inayopitishwa kwenye proxy inayoweka kikomo cha bodies kuwa 1 MB itakataliwa kabla paperless haijaiona, na browser itaonyesha hitilafu ya jumla ya upload.

Jinsi saraka ya consume inavyofanya kazi

Faili ya compose huunganisha ./consume kutoka kwenye saraka ya compose ndani ya container kwa kutumia bind mount. Kila kitu unachoweka humo huingizwa kisha kufutwa kwenye folda hiyo, kwa sababu faili sasa huhifadhiwa kwenye media volume chini ya usimamizi wa paperless.

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

Unapaswa kuona consumer ikichukua jina la faili, ikiendesha OCR, na kukamilisha mchakato kwa mstari unaoripoti kuwa document imeongezwa. Mzunguko mzima huchukua sekunde chache kwa scan ya ukurasa mmoja, na unaweza kuchukua dakika moja au zaidi kwa document ndefu.

Mipangilio miwili hubadilisha jinsi faili zinavyopatikana. PAPERLESS_CONSUMER_RECURSIVE=true hufanya paperless itafute kwenye subfolders, na PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true hubadilisha jina la kila subfolder kuwa tag, kwa hiyo kuweka faili kwenye consume/invoices/2026/ huiwekea tag invoices na 2026. Hii ndiyo filing system rahisi zaidi utakayowahi kujenga.

Detection ndiyo sehemu nyingine. Kwa chaguo-msingi, PAPERLESS_CONSUMER_POLLING_INTERVAL ni 0, ikimaanisha kuwa paperless hutumia arifa za native filesystem zinazotumwa mara moja. Arifa hizo si za kuaminika kwenye network filesystem. Ikiwa consume folder yako ni NFS au SMB share ili network scanner iweze kuandika humo, faili zinaweza kubaki hapo bila kugunduliwa. Suluhisho ni kuweka interval iwe idadi chanya ya sekunde, ili paperless ichanganue folder badala yake.

Lugha za OCR, na gharama zake

PAPERLESS_OCR_LANGUAGE hupokea msimbo wa Tesseract wa herufi tatu, eng kwa chaguo-msingi. Unganisha lugha kwa kutumia alama ya jumlisha, kama ilivyo kwenye deu+eng. Kisha Tesseract hufanya kazi kwa kila lugha iliyoorodheshwa kwenye kila ukurasa, hivyo kila lugha ya ziada huongeza muda wa CPU katika kila uchanganuzi. Kwenye VPS yenye vCPU inayoshirikiwa, tofauti inaweza kuwa kati ya uchanganuzi kumalizika ndani ya sekunde kumi na kumalizika ndani ya dakika moja. Orodhesha tu lugha ambazo hati zako zimeandikwa kwazo.

Image hii inajumuisha Kiingereza, Kijerumani, Kiitaliano, Kihispania na Kifaransa. Kwa lugha nyingine yoyote, ongeza lugha hiyo kwenye PAPERLESS_OCR_LANGUAGES kama orodha iliyotenganishwa kwa nafasi, kwa mfano PAPERLESS_OCR_LANGUAGES=tur ces, kisha uanze upya. Container hupakua vifurushi vya data vya Tesseract wakati wa kuanza, kwa hiyo boot ya kwanza baada ya mabadiliko hayo itakuwa polepole zaidi.

Hifadhi nakala ya database na media

Kunakili Docker volumes wakati PostgreSQL inaendelea kunaweza kutoa backup ambayo haiwezi kurejeshwa. Paperless ina exporter yake, ambayo huandika documents pamoja na JSON manifest ya metadata yote kwenye ./export bind mount:

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

--delete huondoa files za export ambazo hazilingani tena na document ya sasa, kwa hiyo folder hubaki mirror badala ya kuendelea kukua bila kikomo. --no-progress-bar huweka output katika hali safi wakati mchakato huu unaendeshwa na cron, na -T huzuia Compose kuomba terminal ambayo cron haina.

Kurejesha ni document_importer dhidi ya folder hiyo hiyo kwenye stack mpya, jambo linalomaanisha kuwa directory ya export ndiyo kitu pekee unachopaswa kulinda. Itume nje ya seva kwa ratiba kwa kutumia backups za restic zilizosimbwa na kuondoa nakala rudufu kutoka VPS yako, na endesha export kwanza ili restic isiwahi kunasa archive iliyoandikwa kwa nusu.

Thibitisha backup kwa kuhakikisha kuwa export/manifest.json ipo na kwamba idadi ya files inalingana na idadi ya documents kwenye interface. Backup ambayo hujawahi kuorodhesha si backup. Export ya kila usiku inayoanza kushindwa bila taarifa ni mbaya zaidi, kwa hiyo fanya cron job itume exit status yake kwenye server yako ya ntfy ili ujue wiki ambayo inashindwa, badala ya siku ambayo utahitaji kurejesha data.

FAQ

Kwa nini kila ukurasa unarudisha "Bad Request (400)" baada ya kuelekeza domain yangu kwake?

Kwa faili za kawaida za usanidi, hilo halipaswi kutokea, kwa sababu PAPERLESS_ALLOWED_HOSTS inaweka * kwa chaguo-msingi. 400 yenye DisallowedHost kwenye log ya container inamaanisha kuwa PAPERLESS_ALLOWED_HOSTS imewekwa kwenye orodha ambayo haijumuishi domain yako. Weka PAPERLESS_URL=https://paperless.example.com ndani ya docker-compose.env, bila slash ya mwisho, na paperless itaongeza hostname hiyo kwenye orodha, au ondoa mstari wa PAPERLESS_ALLOWED_HOSTS. Kisha endesha docker compose up -d ili kuunda tena container. Kuhariri faili ya env pekee hakufanyi chochote, kwa sababu container inayoendesha inaendelea kutumia environment iliyokuwa nayo ilipoanzishwa.

Niliweka PDF kwenye folda ya consume lakini hakuna kilichotokea. Tatizo ni nini?

Kwanza kagua docker compose logs webserver. Kosa la permission linamaanisha kuwa USERMAP_UID na USERMAP_GID hazilingani na account inayomiliki faili, kwa hiyo rekebisha hizo kisha uunde tena container. Kukosekana kabisa kwa mstari wa log kunamaanisha kuwa tukio la faili halikufika. Hili hutokea kwenye network shares kwa sababu arifa za asili za filesystem si za kuaminika huko. Weka PAPERLESS_CONSUMER_POLLING_INTERVAL kwenye thamani kama 30, na paperless itachanganua folda kila baada ya sekunde 30 badala yake.

Je, ninaweza kuendesha paperless-ngx kwa SQLite badala ya PostgreSQL?

Ndiyo, docker-compose.sqlite.yml inaungwa mkono na hutumia memory kidogo, jambo linalofaa kwa VPS ndogo. Hasara huonekana archive yako inapokua: full-text search na uhariri wa bulk wa tags hupungua kasi kwa kiasi kinachoonekana unapokuwa na maelfu ya nyaraka. Kuhamia baadaye kunahitaji export na import, kwa hiyo chagua PostgreSQL sasa ikiwa unatarajia archive itaendelea kukua.

Archive ya scans inahitaji nafasi kiasi gani ya disk?

Kwa makadirio, takriban mara mbili ya ukubwa wa mafaili yako ya chanzo. Paperless huhifadhi faili la awali bila kulibadilisha na huhifadhi PDF ya pili yenye OCR na text layer inayoweza kutafutwa, pamoja na thumbnails ndogo. Scan ya maandishi pekee yenye 200 KB hubaki ndogo. Scan ya rangi yenye 30 MB ya mkataba mrefu huhifadhi takriban 60 MB. Ongeza directory ya export ikiwa unaweka kwenye disk hiyo hiyo, na archive hiyo itatumia nafasi mara tatu kwenye disk.

Je, ninahitaji containers za Tika na Gotenberg?

Ni ikiwa tu unataka mafaili ya Word, Excel au OpenDocument yawekwe kwenye index pamoja na PDF zako. Hubadilisha format hizo kuwa PDF ili paperless iweze kufanya OCR na kuzitafuta. Pia huongeza containers nyingine mbili zinazoendesha na matumizi ya memory ya mamia machache ya megabytes, kwa hiyo ziruke kwenye server ndogo ikiwa kila kitu unachoweka tayari ni PDF au image.

Je, makala hii ilikusaidia?

#paperless-ngx#documents#self-hosting#docker#ocr