Jinsi ya kusakinisha Paperless-ngx kwenye VPS

Unachojenga

Paperless-ngx kwenye VPS hubadilisha folda ya karatasi zilizochanganuliwa (scanned) kuwa kumbukumbu inayotafutika. Unapoweka PDF kwenye saraka inayofuatiliwa (watched directory), seva huifanyia OCR (optical character recognition), huchomoa maandishi, hukisia tarehe na mhusika, kisha huihifadhi. Usakinishaji huu ni faili moja ya Docker Compose yenye huduma nne. Kila kitu baada ya hapo ni usanidi, na mwongozo huu unatumia muda mwingi hapo, kwa sababu hapo ndipo usakinishaji unapofeli. Hii si maktaba ya picha: OCR na kukisia mhusika hakufanyi kazi kwa folda ya picha za likizo (JPEGs), kwa hivyo ziweke kwenye seva ya picha iliyoundwa kwa ajili hiyo na uweke paperless kwa ajili ya karatasi pekee.

Paperless-ngx ni fork ya jamii inayodumishwa ya mradi wa awali wa Paperless. Ni ya bure, inajihostiwa mwenyewe, na huhifadhi nyaraka zako kama faili za kawaida kwenye diski, kwa hiyo huwezi kufungiwa nje ya kumbukumbu yako mwenyewe. Kuiendesha kwenye VPS badala ya kompyuta ya nyumbani kunamaanisha kwamba scans zako zinapatikana kutoka mahali popote bila kufungua port kwenye router ya nyumbani, na inaendana vizuri na instance ya kibinafsi ya Nextcloud kwa faili ambazo si za karatasi. Mantiki hiyo hiyo inahusu desktop ambayo scanner yako imeunganishwa kwayo, kwa sababu relay yako mwenyewe ya RustDesk kwenye VPS hiyo hukuwezesha kuendesha mashine hiyo ukiwa mahali pengine bila pia kutoboa router.

Kile ambacho stack huendesha kwa uhalisia

Faili rasmi la compose huanzisha container nne, na kufahamu kazi ya kila moja hufanya logs kusomeka kwa urahisi.

• webserver: image ya paperless-ngx yenyewe. Huendesha kiolesura cha wavuti, API, consumer inayofuatilia folda yako ya ingizo, na wafanyakazi wa kazi za Celery wanaofanya OCR.
• db: PostgreSQL. Huhifadhi metadata, tag, waasiliani, na majedwali ya index ya utafutaji wa maandishi kamili. Haishiki faili zako za PDF.
• broker: Valkey, hifadhi ya key-value inayooana na Redis. Ni foleni ya kazi kati ya mchakato wa wavuti na wafanyakazi.
• gotenberg na tika: ni za hiari, zinapatikana tu katika lahaja za -tika compose. Hubadilisha hati za Office (.docx, .xlsx, .odt) kuwa PDF ili paperless iweze kuziweka kwenye index.

Kufikia Julai 2026, faili la postgres compose hufunga matoleo ya docker.io/library/postgres:18 na docker.io/valkey/valkey:9-alpine, na kuvuta programu kutoka ghcr.io/paperless-ngx/paperless-ngx:latest.

Mahitaji ya awali

• VPS ya Ubuntu 24.04 inayotumia KVM yenye ufikiaji wa sudo, na Docker pamoja na Compose plugin ikiwa imesakinishwa. Ikiwa sehemu hii ni ngeni kwako, anza na misingi ya Docker Compose kwa VPS kisha urudi hapa.
• Jina la domain lenye A record inayoelekeza kwenye VPS hiyo. Paperless hukataa kufanya kazi kwenye hostname ambayo haijaelezwa, kwa hivyo jambo hili ni muhimu mapema kuliko unavyotarajia.
• Kumbukumbu (RAM) ndiyo kizuizi kikuu. PostgreSQL, Valkey, gunicorn na Tesseract OCR worker vyote vikiwa vinafanya kazi kwa wakati mmoja vinaweza kutosha kwenye 2 GB kwa matumizi madogo. Tenga 4 GB ikiwa unapanga kuingiza kiasi kikubwa cha skani, kwa sababu OCR kwenye PDF kubwa yenye kurasa nyingi husababisha matumizi makubwa ya kumbukumbu ambayo yanaweza kusababisha worker kufungwa na kernel kupitia out-of-memory killer.
• Diski: kumbukumbu yako huhifadhiwa mara mbili, faili asilia na PDF ya kumbukumbu iliyopitia OCR, kwa hivyo tenga nafasi ya takriban mara mbili ya ukubwa wa skani 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 kuanza kwa mara ya kwanza

Mipangilio miwili si ya hiari. Tengeneza ufunguo wa siri (secret key) kwa kutumia amri iliyoainishwa kwenye nyaraka za mradi:

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 inakuja ikiwa na thamani halisi ya change-me. Inatumika kusaini kuki za kikao (session cookies), kwa hivyo kuiacha hivyo inamaanisha mtu yeyote anayejua thamani hiyo ya awali anaweza kughushi kikao. Iweke kabla ya kuanza kwa mara ya kwanza, kwa sababu kuibadilisha baadaye kutawatoa watumiaji wote kwenye mifumo yao.

PAPERLESS_URL ndiyo inayokuokoa muda mwingi. Paperless ni programu ya Django, na Django inathibitisha kichwa cha habari (header) cha Host kwa kila ombi. Sanidi PAPERLESS_URL na itajaza ALLOWED_HOSTS, CORS_ALLOWED_HOSTS na CSRF_TRUSTED_ORIGINS kwa ajili yako. Ukiacha ikiwa wazi, ukaelekeza domain kwenye seva, na kila ukurasa ukarejesha Bad Request (400) ikiwa na DisallowedHost kwenye logi ya container, basi tatizo ni hili. Iandike bila mkwaju (slash) mwishoni na bila njia (path) yoyote.

USERMAP_UID na USERMAP_GID huweka mtumiaji anayeendesha container. Zilinganishe na akaunti yako mwenyewe, ambayo unaweza kuiangalia kwa kutumia id -u na id -g. Ikiwa hazilingani, faili unazozinakili kwenye folda ya consume hazitasomeka na consumer, na logi itaonyesha kosa la ruhusa (permission error) badala ya kuingiza faili (import).

Anzisha 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 huomba jina la mtumiaji, barua pepe, na nenosiri. Hakuna login chaguo-msingi, kwa hivyo kuruka hatua hii kutakuacha kwenye ukurasa wa kuingia ambao hautakubali chochote. Subiri mstari wa logi unaoonyesha kuwa seva inasikiliza kwenye port 8000 kabla ya kujaribu kutumia kivinjari. Kuanzishwa kwa mara ya kwanza pia huendesha migrations za database, jambo linalochukua dakika moja au mbili.

Ijaribu ndani ya seva kabla ya kuhusisha domain:

curl -I http://127.0.0.1:8000

302 kuelekeza kwenye /accounts/login/ inamaanisha kuwa stack iko katika hali nzuri.

Weka HTTPS mbele yake

Faili la kawaida la compose huchapisha 8000:8000, ambalo hufungamana na kila interface. Kwenye VPS ya umma, hii huchapisha kumbukumbu yako yote ya hati kupitia HTTP ya kawaida kwa yeyote anayepata anwani hiyo. Badilisha mstari wa port ili ufungamane na loopback pekee:

    ports:
      - "127.0.0.1:8000:8000"

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

Proxy yoyote unayotumia, lazima itume X-Forwarded-Proto: https. Bila hiyo, Django huamini kuwa ombi limefika kupitia HTTP, ukaguzi wa asili kwenye fomu ya kuingia (login) hushindwa, na unapata CSRF verification failed. Request aborted. kwenye ukurasa unaoonekana kuwa sahihi. Nusu nyingine ya marekebisho hayo ni PAPERLESS_URL kuwekwa kwenye anwani kamili ya https:// unayochapa kwenye kivinjari.

Pia ongeza kikomo cha ukubwa wa kupakia (upload) cha proxy. Scan ya 40 MB inayopitia proxy inayozuia miili ya ujumbe (bodies) kwa 1 MB hukataliwa kabla paperless haijaiona, na kivinjari huripoti hitilafu ya jumla ya upakiaji.

Jinsi saraka ya consume inavyofanya kazi

Faili la compose hufanya bind-mount ya ./consume kutoka kwenye saraka ya compose kwenda kwenye container. Kila kitu unachoweka hapo huletwa ndani na kisha kufutwa kutoka kwenye folda hiyo, kwa sababu faili hilo sasa linakaa kwenye volume ya media chini ya usimamizi wa paperless.

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

Unapaswa kuona consumer akichukua jina la faili, akifanya OCR, na kumaliza kwa mstari unaoarifu kuwa hati imeongezwa. Mzunguko mzima huchukua sekunde chache kwa skani ya ukurasa mmoja na unaweza kuchukua dakika moja au zaidi kwa hati ndefu.

Mipangilio miwili hubadilisha jinsi faili zinavyopatikana. PAPERLESS_CONSUMER_RECURSIVE=true huifanya paperless kutafuta kwenye subfolders, na PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true hugeuza kila jina la subfolder kuwa tag, kwa hivyo kuweka faili ndani ya consume/invoices/2026/ hulipa tag ya invoices na 2026. Huo ndio mfumo wa kuhifadhi faili wa bei nafuu zaidi utakaowahi kuujenga.

Ugunduzi ndio nusu nyingine ya kazi. Kwa chaguo-msingi PAPERLESS_CONSUMER_POLLING_INTERVAL ni 0, ikimaanisha kuwa paperless hutumia arifa za kernel filesystem, ambazo hufanya kazi mara moja. Arifa hizo hazivuki kwenye network filesystem. Ikiwa folda yako ya consume ni share ya NFS au SMB ili scanner ya mtandao iweze kuandika humo, hakuna kitakachogunduliwa, na suluhisho ni kuweka muda wa interval kuwa namba chanya ya sekunde ili paperless ichunguze folda hiyo badala yake.

Lugha za OCR, na gharama zake

PAPERLESS_OCR_LANGUAGE hutumia msimbo wa herufi tatu wa Tesseract, eng ikiwa chaguo-msingi. Unganisha lugha kwa kutumia alama ya kujumlisha, kama ilivyo katika deu+eng. Tesseract hujaribu kila lugha na kuhifadhi matokeo bora zaidi, kwa hivyo kila lugha ya ziada huongeza muda wa CPU unaotumika kwa kila ukurasa. Kwenye VPS yenye vCPU inayoshirikiwa, hii ndiyo tofauti kati ya skani inayokamilika kwa sekunde kumi na ile inayochukua dakika moja. Orodhesha tu lugha ambazo hati zako zimeandikwa kwa kweli.

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

Hifadhi nakala ya database na media

Kunakili Docker volumes wakati PostgreSQL inaendelea kufanya kazi kutakupa nakala ambayo huenda isikubali kurejeshwa. Paperless inakuja na exporter yake yenyewe, ambayo huandika hati pamoja na JSON manifest ya metadata yote kwenye ./export bind mount:

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

--delete huondoa faili zilizosafirishwa ambazo hazilingani tena na hati ya sasa, hivyo folda hiyo inabaki kuwa kioo badala ya kuendelea kukua bila kikomo. --no-progress-bar huweka matokeo yakiwa safi wakati huu unapoendeshwa kutoka kwa cron.

Kurejesha hufanywa kwa document_importer dhidi ya folda hiyo hiyo kwenye stack mpya, jambo linalomaanisha kuwa saraka ya export ndiyo kitu pekee unachopaswa kukiweka salama. Ipeleke nje ya seva kulingana na ratiba ukitumia encrypted, deduplicated restic backups from your VPS, na uendeshe export kwanza ili restic isije ikachukua archive iliyoandikwa nusu.

Thibitisha backup kwa kukagua kwamba export/manifest.json ipo na kwamba idadi ya mafaili inalingana na idadi ya nyaraka iliyo kwenye interface. Backup ambayo hujawahi kuorodhesha si backup. Export ya kila usiku inayoanza kushindwa kimya kimya ni mbaya zaidi. Kwa hiyo, cron job itume exit status yake kwenye server yako mwenyewe ya ntfy, na utagundua wiki ambayo inashindwa badala ya siku ambayo unahitaji kurejesha backup.

FAQ

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

Django ilikataa header ya Host kwa sababu domain yako haipo kwenye ALLOWED_HOSTS. Weka PAPERLESS_URL=https://paperless.example.com ndani ya docker-compose.env, bila alama ya mkwaju (slash) mwishoni, kisha endesha docker compose up -d ili kutengeneza upya container. Kuhariri faili ya env pekee hakusaidii, kwa sababu container inayofanya kazi huhifadhi mazingira iliyoanza nayo.

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

Angalia docker compose logs webserver kwanza. Hitilafu ya ruhusa (permission error) inamaanisha kuwa USERMAP_UID na USERMAP_GID hazilingani na akaunti inayomiliki faili hiyo, kwa hivyo rekebisha hayo na utengeneze upya container. Kutokuwepo kwa mstari wowote kwenye logi inamaanisha kuwa tukio la faili halikufika, jambo linalotokea kwenye network shares kwa sababu arifa za kernel hazivuki kwenda huko. Weka PAPERLESS_CONSUMER_POLLING_INTERVAL kuwa kitu kama 30 na paperless itachanganua folda hiyo kila baada ya sekunde 30 badala yake.

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

Ndiyo, docker-compose.sqlite.yml inakubalika na inatumia kumbukumbu kidogo, jambo linalofaa kwa VPS ndogo. Hasara yake huonekana kadiri kumbukumbu yako inavyokua: utafutaji wa maandishi yote (full-text search) na uhariri wa wingi wa tag hupungua kasi kwa kiasi kikubwa unapofikia maelfu ya hati. Kuhama baadaye kunamaanisha kufanya export na import, kwa hivyo chagua PostgreSQL sasa ikiwa unatarajia kumbukumbu yako kuendelea kukua.

Je, kumbukumbu ya scans inahitaji nafasi kiasi gani kwenye diski?

Takriban mara mbili ya ukubwa wa faili zako asilia. Paperless huhifadhi faili asilia bila kuigusa na kuhifadhi PDF ya pili iliyopitia OCR yenye safu ya maandishi yanayoweza kutafutwa, pamoja na vijipicha (thumbnails) vidogo. Scan ya maandishi pekee ya 200 KB hubaki ndogo. Scan ya rangi ya 30 MB ya mkataba mrefu huhifadhi takriban 60 MB. Ongeza saraka ya export ikiwa utaiweka kwenye diski hiyo hiyo, na kumbukumbu hiyo hiyo itakuwa kwenye diski mara tatu.

Je, ninahitaji container za Tika na Gotenberg?

Ni ikiwa tu unataka faili za Word, Excel au OpenDocument ziwekwe kwenye index pamoja na PDF zako. Hizo hubadilisha fomati hizo kuwa PDF ili paperless iweze kuzifanyia OCR na kuzitafuta. Pia huongeza container mbili zaidi zinazofanya kazi na mamia kadhaa ya megabytes ya kumbukumbu, kwa hivyo ziondoe kwenye seva ndogo ikiwa kila kitu unachohifadhi tayari ni PDF au picha.