SSD Nodes Learn Hosting plans →
Mga Gabay Matt ConnorNi Matt Connor · Na-update 2026-10-25

Paperless-ngx sa VPS: self-host na document archive

I-set up ang Paperless-ngx sa VPS gamit ang Docker Compose, official Postgres stack, PAPERLESS_URL, consume folder, OCR languages, HTTPS, at backups.

Ang binubuo mo

Ginagawang searchable archive ng Paperless-ngx sa isang VPS ang isang folder ng mga na-scan na papel. Maglagay ng PDF sa watched directory. Tatakbuhin ng server ang OCR (optical character recognition) dito, ie-extract ang text, tatantiyahin ang petsa at correspondent, at ia-archive ito. Isang Docker Compose file na may apat na service ang kailangan para sa installation. Pagkatapos nito, configuration na ang lahat. Karamihan ng gabay na ito ay nakatuon dito dahil dito kadalasang pumapalya ang mga installation. Hindi ito photo library. Walang maitutulong ang OCR at correspondent guessing sa isang folder ng mga JPEG mula sa bakasyon. Ilagay ang mga iyon sa isang photo server na para sa mga ito at gamitin ang paperless para sa mga dokumento. Ganito rin ang paghihiwalay para sa video. Ang koleksiyon ng mga na-rip na pelikula ay dapat nasa media server, kung saan ang isang bagay na gaya ng Jellyfin front end na ginawang parang 90s rental store ay naglalagay ng diin sa pag-browse sa halip na sa paghahanap.

Ang Paperless-ngx ay ang pinapanatiling community fork ng orihinal na Paperless project. Libre ito, self-hosted, at ini-store ang iyong mga dokumento bilang mga plain file sa disk. Kaya hindi ka mawawalan ng access sa sarili mong archive. Kapag pinatakbo ito sa VPS sa halip na sa home box, maa-access ang iyong mga scan kahit saan nang hindi nagbubukas ng port sa home router. Angkop din itong ipares sa isang private Nextcloud instance para sa mga file na hindi papel. Saklaw ng parehong prinsipyo ang desktop na nakakonekta sa iyong scanner. Sa pamamagitan ng sarili mong RustDesk relay sa VPS na iyon, makokontrol mo ang machine na iyon mula sa ibang lugar nang hindi rin gumagawa ng butas sa router.

Ano talaga ang pinapatakbo ng stack

Nagsisimula ang official compose file ng apat na container. Kapag alam mo ang gawain ng bawat isa, mas madaling basahin ang logs.

  • webserver: ang paperless-ngx image mismo. Pinapatakbo nito ang web interface, API, consumer na nagmo-monitor sa input folder mo, at mga Celery task worker na nagsasagawa ng OCR.
  • db: PostgreSQL. Dito naka-store ang metadata, tags, correspondents, at mga table ng full-text search index. Hindi nito naka-store ang mga PDF mo.
  • broker: Valkey, isang Redis-compatible na key-value store. Ito ang task queue sa pagitan ng web process at mga worker.
  • gotenberg at tika: optional lamang at ginagamit sa mga -tika compose variant. Kino-convert ng mga ito ang mga Office document (.docx, .xlsx, .odt) sa PDF para ma-index ng paperless.

Noong October 2026, naka-pin sa postgres compose file ang docker.io/library/postgres:18 at docker.io/valkey/valkey:9-alpine, at kinukuha nito ang app mula sa ghcr.io/paperless-ngx/paperless-ngx:latest.

Mga Kinakailangan

  • Isang Ubuntu 24.04 KVM VPS na may sudo access, at may naka-install nang Docker kasama ang Compose plugin. Kung bago sa iyo ang bahaging ito, magsimula sa mga pangunahing konsepto ng Docker Compose para sa VPS at bumalik dito.
  • Isang domain name na may A record na tumuturo sa VPS. Hindi tatanggap ang Paperless ng sign-in sa HTTPS gamit ang hostname na hindi nito nalaman, kaya mas maaga itong kailangang i-configure kaysa sa inaasahan mo.
  • Ang memory ang pangunahing limitasyon. Kasya sa 2 GB para sa magaan na paggamit ang PostgreSQL, Valkey, Granian web server, at isang Tesseract OCR worker kapag sabay-sabay silang nasa memory. Gumamit ng 4 GB kung plano mong mag-import ng backlog na daan-daang scan, dahil ang OCR ng malaking PDF na maraming page ang nagdudulot ng biglang pagtaas ng memory at maaaring maging sanhi upang patayin ng kernel out-of-memory killer ang worker.
  • Disk: dalawang beses na naka-store ang archive mo—ang original file at isang OCR'd archive PDF—kaya maglaan ng humigit-kumulang doble sa laki ng mga scan mo.

Kunin ang opisyal na compose files

May interactive installer:

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

Nagtatanong ito at isinusulat ang mga file para sa iyo. Apat na command lang ang manu-manong paraan, at malalaman mo kung nasaan ang lahat. Ito ang kailangan mo sa server na ikaw ang magme-maintain.

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

Nasa iisang directory ang mga variant: docker-compose.sqlite.yml, docker-compose.mariadb.yml, at isang -tika version ng bawat isa. Piliin ang postgres para sa bagong install. Ayos ang SQLite para sa ilang daang dokumento, pero bumabagal ang full-text search index bago pa bumagal ang PostgreSQL.

May isang linya ang file na .env: COMPOSE_PROJECT_NAME=paperless. Nagiging prefix ang pangalang ito sa bawat container at volume. Huwag itong i-delete at pagkatapos ay magtaka kung bakit hindi mahanap ng docker compose down -v ang iyong data.

I-configure ang docker-compose.env bago ang unang start

Hindi optional ang dalawang setting. I-generate ang secret key gamit ang command na nakadokumento sa project:

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

Pagkatapos, i-edit ang 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

Ang PAPERLESS_SECRET_KEY ay kasama bilang literal na value na change-me. Ginagamit ito para pumirma ng session tokens. Itinuturing ng mga kasalukuyang release na unset ang placeholder na ito. Hindi magsisimula ang paperless habang missing, blank, o change-me pa rin ang key. Kaya hindi mag-start ang stack hanggang mapalitan mo ito. I-set ito bago ang unang start, dahil kapag binago mo ito sa huli, mali-log out ang lahat ng user.

Ang PAPERLESS_URL ang makakatipid sa iyo ng isang oras. Django application ang Paperless, at chine-check ng Django ang parehong Host header at ang origin na iniuulat ng browser sa sign-in form. Kapag sine-set mo ang PAPERLESS_URL, awtomatiko nitong idinaragdag ang iyong address sa ALLOWED_HOSTS, CORS_ALLOWED_HOSTS, at CSRF_TRUSTED_ORIGINS. Kapag iniwan mo itong walang laman at nagturo ka ng domain sa server, naglo-load pa rin ang sign-in page dahil nagde-default ang PAPERLESS_ALLOWED_HOSTS sa *. Ngunit mabibigo ang pagsusumite nito sa HTTPS dahil sa CSRF verification failed. Request aborted., sapagkat hindi trusted origin ang iyong domain. Isulat ito nang walang trailing slash at walang path.

Tinutukoy ng USERMAP_UID at USERMAP_GID ang user na gagamitin ng container. Itugma ang mga ito sa sarili mong account, na mava-verify gamit ang id -u at id -g. Kapag hindi magkatugma ang mga ito, hindi mababasa ng consumer ang mga file na kinopya mo sa consume folder. Permission error ang lalabas sa log sa halip na import.

Simulan ang stack at gawin ang unang user

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

createsuperuser ay humihingi ng username, email, at password. Walang default na login. Kung lalaktawan mo ang hakbang na ito, hihilingin ng web interface sa unang magbukas nito na gumawa ng superuser. Habang bukas pa sa internet ang port 8000, maaaring hindi ikaw ang unang makapagbukas nito. Kaya gawin agad ang account mula sa shell. Hintayin ang log line na nagsasabing nakikinig na ang server sa port 8000 bago subukan sa browser. Sa unang pagsisimula, pinapatakbo rin ang database migrations. Karaniwan itong tumatagal ng isa o dalawang minuto.

Suriin muna ito locally bago gumamit ng domain:

curl -I http://127.0.0.1:8000

Ang 302 redirect papunta sa /accounts/login/ ay nangangahulugang healthy ang stack.

Ilagay ang HTTPS sa harap nito

Ang stock compose file ay nagpa-publish ng 8000:8000, na nagbi-bind sa lahat ng interface. Sa public VPS, inilalantad nito sa plain HTTP ang buong document archive mo sa sinumang makahanap ng address. Baguhin ang port line upang sa loopback lamang ito mag-bind:

    ports:
      - "127.0.0.1:8000:8000"

Pagkatapos, i-terminate ang TLS (transport layer security) sa isang reverse proxy at i-forward ito sa 127.0.0.1:8000. Kung ito lamang ang app sa server, gagana ang anumang proxy na may ACME (automatic certificate management environment) client. Kung nagpapatakbo ka ng ilang container sa likod ng iisang certificate setup, sundin ang pattern ng Traefik reverse proxy para sa maraming Docker Compose app at i-attach ang webserver service sa proxy network nang walang published port.

Anuman ang proxy na gamitin mo, ang origin check ng login form ang karaniwang pinagmumulan ng problema sa HTTPS setup. Binabalewala ng Paperless ang X-Forwarded-Proto maliban kung itatakda mo ang PAPERLESS_PROXY_SSL_HEADER, na naka-off bilang default. Dahil dito, itinuturing ng Django na plain HTTP ang bawat proxied request, at papasa lamang ang https:// origin na ipinapadala ng browser kung nakalista ito bilang trusted. Ang pagtatakda ng PAPERLESS_URL sa eksaktong https:// address na tina-type mo sa browser ang naglalagay dito sa listahang iyon. Kung hindi ito itatakda, makakakuha ka ng CSRF verification failed. Request aborted. sa isang page na mukhang tama.

Dagdagan din ang upload size limit ng proxy. Ang 40 MB na scan na dumadaan sa proxy na naglilimita sa request body sa 1 MB ay tatanggihan bago pa ito makita ng Paperless, at generic upload failure ang ipapakita ng browser.

Paano gumagana ang consume directory

Ang compose file ay nagbi-bind-mount ng ./consume mula sa compose directory papunta sa container. Anumang ilagay mo roon ay ini-import at pagkatapos ay dine-delete mula sa folder, dahil nasa media volume na ang file at pinamamahalaan na ito ng paperless.

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

Dapat mong makitang kinukuha ng consumer ang filename, nagpapatakbo ng OCR, at nagtatapos sa linyang nagsasaad na naidagdag na ang dokumento. Ilang segundo lang ang buong cycle para sa one-page scan, ngunit maaaring umabot ng isang minuto o higit pa para sa mahabang dokumento.

Dalawang setting ang nagbabago kung paano hinahanap ang mga file. Ginagawa ng PAPERLESS_CONSUMER_RECURSIVE=true na maghanap ang paperless sa mga subfolder, at ginagawang tag ng PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true ang pangalan ng bawat subfolder. Kaya kapag naglagay ka ng file sa consume/invoices/2026/, lalagyan ito ng tag na invoices at 2026. Ito ang pinakamurang filing system na mabubuo mo.

Ang detection ang kabilang bahagi. Bilang default, ang PAPERLESS_CONSUMER_POLLING_INTERVAL ay 0, ibig sabihin ay gumagamit ang paperless ng native filesystem notifications na agad nagti-trigger. Hindi maaasahan ang mga notification na ito sa network filesystem. Kung NFS o SMB share ang consume folder mo upang maisulatan ito ng network scanner, maaaring manatiling hindi natutukoy ang mga file. Ang solusyon ay itakda ang interval sa positibong bilang ng mga segundo upang sa halip ay regular na i-scan ng paperless ang folder.

Mga wika ng OCR at ang gastos ng mga ito

Tumatanggap ang PAPERLESS_OCR_LANGUAGE ng three-letter Tesseract code. Ang default ay eng. Pagsamahin ang mga wika gamit ang plus sign, gaya ng deu+eng. Gagamitin ng Tesseract ang bawat nakalistang wika sa bawat page, kaya ang bawat karagdagang wika ay nagdaragdag ng CPU time sa bawat scan. Sa VPS na may shared vCPU, ito ang maaaring magpabago sa oras ng pagtatapos ng scan mula sampung segundo hanggang isang minuto. Ilista lamang ang mga wikang aktuwal na ginagamit sa iyong mga dokumento.

May kasamang English, German, Italian, Spanish, at French ang image. Para sa iba pang wika, idagdag ang wika sa PAPERLESS_OCR_LANGUAGES bilang listahang pinaghihiwalay ng spaces, halimbawa PAPERLESS_OCR_LANGUAGES=tur ces, at pagkatapos ay mag-restart. Dina-download ng container ang Tesseract data packs sa startup, kaya mas mabagal ang unang boot pagkatapos ng pagbabagong ito.

I-back up ang database at media

Ang pagkopya ng Docker volumes habang tumatakbo ang PostgreSQL ay gumagawa ng backup na maaaring hindi ma-restore. May sarili itong exporter ang Paperless, na nagsusulat ng mga dokumento at JSON manifest ng lahat ng metadata sa ./export bind mount:

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

Tinatanggal ng --delete ang mga exported file na hindi na tumutugma sa kasalukuyang dokumento, kaya nananatiling mirror ang folder at hindi patuloy na lumalaki. Pinananatiling malinis ng --no-progress-bar ang output kapag pinapatakbo ito mula sa cron, at pinipigilan ng -T ang Compose na humingi ng terminal na wala sa cron.

Ang pag-restore ay document_importer laban sa folder na iyon sa isang bagong stack. Ibig sabihin, ang export directory lamang ang kailangan mong panatilihing ligtas. Ipadala ito sa offsite storage ayon sa iskedyul gamit ang encrypted at deduplicated na restic backup mula sa VPS, at unahin ang export para hindi makuha ng restic ang archive na hindi pa tapos isulat.

I-verify ang backup sa pamamagitan ng pagsuri kung umiiral ang export/manifest.json at kung tumutugma ang bilang ng file sa bilang ng mga dokumento sa interface. Ang backup na hindi mo pa kailanman na-lista ay hindi maituturing na backup. Mas masama pa ang nightly export na tahimik na tumitigil sa paggana, kaya ipasa ng cron job ang exit status nito sa sarili mong ntfy server. Sa ganitong paraan, malalaman mong may problema sa linggong nagsimula ito, sa halip na sa araw na kailangan mo nang mag-restore.

FAQ

Bakit nagbabalik ng "Bad Request (400)" ang bawat page matapos kong ituro ang domain ko rito?

Sa stock files, hindi ito dapat mangyari dahil ang PAPERLESS_ALLOWED_HOSTS ay naka-default sa *. Ang 400 na may DisallowedHost sa container log ay nangangahulugang na-set ang PAPERLESS_ALLOWED_HOSTS sa isang listahan na hindi kasama ang domain mo. I-set ang PAPERLESS_URL=https://paperless.example.com sa docker-compose.env, nang walang trailing slash, at idaragdag ng paperless ang hostname na iyon sa listahan. Maaari mo ring alisin ang PAPERLESS_ALLOWED_HOSTS line. Pagkatapos, patakbuhin ang docker compose up -d upang muling gawin ang container. Walang epekto ang pag-edit lang sa env file dahil ginagamit pa rin ng tumatakbong container ang environment na nakuha nito noong nagsimula ito.

Naglagay ako ng PDF sa consume folder pero walang nangyari. Ano ang mali?

Suriin muna ang docker compose logs webserver. Ang permission error ay nangangahulugang hindi tugma ang USERMAP_UID at USERMAP_GID sa account na may-ari ng file, kaya ayusin ang mga iyon at muling gawin ang container. Kung walang anumang log line, hindi nakarating ang file event. Nangyayari ito sa network shares dahil hindi maaasahan doon ang native filesystem notifications. I-set ang PAPERLESS_CONSUMER_POLLING_INTERVAL sa gaya ng 30 at isi-scan ng paperless ang folder kada 30 segundo sa halip.

Maaari ko bang patakbuhin ang paperless-ngx gamit ang SQLite sa halip na PostgreSQL?

Oo, suportado ang docker-compose.sqlite.yml at mas kaunti ang memory na ginagamit nito, kaya angkop ito sa maliit na VPS. Lumilitaw ang tradeoff habang lumalaki ang archive: kapansin-pansing bumabagal ang full-text search at maramihang pag-edit ng tag kapag umabot sa libo-libo ang mga dokumento. Ang paglipat sa ibang database sa hinaharap ay nangangailangan ng export at import, kaya piliin na ngayon ang PostgreSQL kung inaasahan mong patuloy na lalaki ang archive.

Gaano karaming disk space ang aktuwal na kailangan ng archive ng mga scan?

Humigit-kumulang dalawang beses ng laki ng source files. Pinananatili ng Paperless ang orihinal na file at nag-iimbak ng ikalawang OCR'd PDF na may searchable text layer, pati ng maliliit na thumbnail. Mananatiling maliit ang 200 KB na text-only scan. Ang 30 MB na color scan ng mahabang kontrata ay kumokonsumo ng humigit-kumulang 60 MB. Idagdag ang export directory kung nasa parehong disk ito. Sa ganitong kaso, tatlong beses ng laki ang disk space na kakailanganin ng parehong archive.

Kailangan ko ba ang Tika at Gotenberg containers?

Kailangan lamang ang mga ito kung gusto mong ma-index ang Word, Excel, o OpenDocument files kasama ng mga PDF. Kino-convert ng mga ito ang mga format na iyon sa PDF upang ma-OCR at ma-search ng paperless. Nagdaragdag din ang mga ito ng dalawa pang tumatakbong container at ilang daang megabytes ng memory. Kaya laktawan ang mga ito sa maliit na server kung PDF o image na ang lahat ng dina-file mo.

Nakatulong ba ang artikulong ito?

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