Paperless-ngx di VPS: Arsip Dokumen Auto-OCR

Coba inget-inget, kapan terakhir kali kamu nyari kontrak sewa atau struk garansi yang udah discan setahun lalu? Kalau jawabannya susah, kamu gak sendirian. Kebanyakan orang mikirnya taro scan dokumen di Google Drive atau Dropbox udah cukup. Padahal nyarinya tetep manual, buka folder satu-satu, scroll nama file yang formatnya “scan001.pdf” sampai “scan247.pdf”. Gak ada cara cari berdasarkan isi dokumen. Nah, di sinilah Paperless-ngx masuk. Ini bukan sekadar tempat nyimpen file, tapi sistem arsip digital yang bisa baca isi dokumen kamu lewat OCR, terus bikin semuanya bisa dicari kayak Google tapi khusus buat dokumen pribadi atau bisnis kamu. Di artikel ini saya bakal bahas cara install Paperless-ngx di VPS pakai Docker Compose dari nol, lengkap dengan penjelasan detail di setiap langkahnya.

Apa Itu Paperless-ngx Sebenarnya

Paperless-ngx itu aplikasi open source buat manajemen dokumen digital yang bisa kamu host sendiri di server. Nama “ngx” itu singkatan dari “next generation” – ini versi lanjutan dari project Paperless yang udah gak aktif dikembangin. Buat yang belum familiar, ini cara kerjanya secara sederhana:

OCR Otomatis: Setiap dokumen yang masuk (PDF, gambar scan, foto) bakal otomatis dibaca teksnya pakai teknologi OCR (Optical Character Recognition). Jadi walaupun dokumen kamu cuma berupa gambar hasil scan, Paperless-ngx bisa “baca” tulisan di dalamnya dan convert jadi teks yang bisa dicari
Full-Text Search: Setelah teks diekstrak, kamu bisa cari dokumen berdasarkan isinya. Ketik “asuransi” di kolom pencarian, semua dokumen yang mengandung kata itu langsung muncul – walaupun nama filenya cuma “scan001.pdf”
Auto-Tagging: Kamu bisa bikin aturan otomatis. Misalnya kalau isi dokumen ada kata “PLN” atau “listrik”, otomatis dikasih tag “Tagihan” dan kategori “PLN”. Jadi dokumen kekelompok sendiri tanpa kamu sortir manual
Consume Folder: Ada folder khusus yang fungsinya kayak kotak masuk. Tinggal drop file ke situ, Paperless-ngx otomatis ambil, proses OCR, dan arsipkan. Gak perlu buka dashboard atau upload manual

Di balik layar, Paperless-ngx butuh tiga komponen buat jalan: webserver (buat dashboard dan API), Redis (buat antrian task OCR), dan PostgreSQL (buat nyimpen metadata dokumen). Ketiganya bakal kita jalanin bareng pakai Docker Compose.

Bedanya Sama Google Drive, Nextcloud, dan Tool Lain

Pertanyaan yang paling sering muncul: “Kenapa gak pakai Google Drive aja?” atau “Bukannya Nextcloud udah bisa nyimpen dokumen?” Jawabannya ada di fungsi inti yang beda.

Google Drive dan Dropbox itu cloud storage – tempat nyimpen file. Kamu bisa upload, download, dan share file. Tapi mereka gak ngerti isi dokumen kamu. Pencarian cuma berdasarkan nama file dan metadata dasar. Kalau nama file kamu “scan001.pdf”, ya cuma bisa dicari pakai kata “scan001”. Isi dokumennya gak bisa dicari.

Nextcloud selangkah lebih maju karena bisa di-self-host dan ada plugin full-text search. Tapi Nextcloud itu fokusnya ke file sync dan collaboration, bukan document management. OCR-nya harus install plugin tambahan dan hasilnya gak se-reliable Paperless-ngx yang emang didesain khusus buat itu.

Paperless-ngx fokusnya spesifik ke satu hal: manajemen dan pencarian dokumen. OCR bawaan, auto-tagging bawaan, consume folder bawaan. Semua fitur inti yang kamu butuhin buat arsip digital udah ada tanpa perlu install plugin tambahan. Trade-off-nya, Paperless-ngx bukan buat file sync atau collaboration – dia murni buat arsip dan pencarian dokumen.

Jadi kalau kamu butuh tempat nyimpen dan sync file sehari-hari, tetep pakai Google Drive atau Nextcloud. Tapi kalau kamu butuh sistem arsip yang bisa dicari berdasarkan isi dokumen, Paperless-ngx jawabannya. Dua-duanya bisa jalan bareng tanpa konflik.

Prasyarat Sebelum Install Paperless-ngx di VPS

Sebelum masuk ke instalasi, ada beberapa hal yang wajib disiapin dulu. Jangan skip bagian ini, soalnya kalau ada yang kurang, nanti proses instalasi bakal mentok atau OCR-nya gak jalan dengan bener.

1. VPS dengan Spesifikasi yang Cukup

OCR itu kerjaan yang lumayan berat, apalagi kalau lagi proses banyak dokumen sekaligus. Minimal siapin VPS dengan spek berikut:

RAM: Minimal 2GB, rekomendasi 4GB kalau volume dokumen banyak. OCR bisa makan 500MB-1GB RAM per proses tergantung ukuran dokumen
CPU: Minimal 2 vCPU. OCR itu CPU-intensive, jadi makin banyak core makin cepet prosesnya
Storage: Minimal 30GB, tapi tergantung seberapa banyak dokumen yang bakal disimpen. Satu dokumen PDF rata-rata 1-5MB, jadi kalkulasi sendiri berdasarkan volume arsip kamu
OS: Ubuntu 22.04 atau 24.04 LTS (paling gampang buat pemula)

Cara cek spek VPS kamu sekarang:

free -h          # cek RAM tersedia
df -h            # cek disk space
nproc            # cek jumlah CPU core
lsb_release -a   # cek versi OS

2. Docker dan Docker Compose Sudah Terinstall

Paperless-ngx bakal kita jalanin di dalam Docker container, jadi Docker wajib udah terinstall. Kalau belum, baca dulu panduan Cara Install Docker di Ubuntu VPS yang udah saya tulis sebelumnya. Pastiin Docker Compose juga udah ikut terinstall.

Cara verifikasi:

docker --version
docker compose version

Kalau dua-duanya nunjukin nomor versi, berarti udah siap.

3. Domain atau Subdomain (Opsional tapi Direkomendasikan)

Kalau kamu mau akses dashboard Paperless-ngx lewat HTTPS (dan seharusnya memang begitu, apalagi isinya dokumen sensitif), siapin domain atau subdomain yang A record-nya udah ngarah ke IP VPS kamu. Misalnya dokumen.contoh.com. Nanti kamu bisa pasang reverse proxy kayak Traefik atau Cloudflare Tunnel di depannya buat handle SSL.

4. Port 8010 Tersedia

Paperless-ngx secara default jalan di port 8000 di dalam container, dan kita bakal map ke port 8010 di host. Pastiin port ini belum dipakai service lain di VPS kamu:

sudo lsof -i :8010

Kalau gak ada output, berarti port 8010 masih kosong dan siap dipakai.

5. Secret Key untuk Keamanan

Paperless-ngx butuh secret key buat enkripsi session dan token. Jangan pakai string asal-asalan, generate yang bener pakai command ini:

openssl rand -base64 32

Simpen hasilnya, nanti bakal dipakai di file environment.

Cara Install Paperless-ngx Pakai Docker Compose

Sekarang masuk ke bagian inti. Ikutin langkah-langkah di bawah ini satu per satu.

Paperless ngx vps docker installation flow

Step 1 – Buat Folder Project

mkdir -p /opt/paperless-ngx
cd /opt/paperless-ngx

Folder ini bakal jadi tempat semua konfigurasi dan data Paperless-ngx. Kita juga perlu bikin dua subfolder yang nanti di-mount ke container:

mkdir -p consume export

consume/ – folder “kotak masuk” tempat kamu drop file yang mau diproses OCR
export/ – folder buat export data kalau kamu mau backup atau migrasi

Step 2 – Buat File docker-compose.yml

Masih di folder /opt/paperless-ngx, bikin file docker-compose.yml:

nano docker-compose.yml

Paste isi berikut:

services:
  broker:
    image: redis:8
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: postgres:17
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    env_file: docker-compose.env

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8010:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env

volumes:
  data:
  media:
  pgdata:
  redisdata:

Penjelasan setiap komponen:

broker (Redis): Message broker buat antrian task. Setiap dokumen yang masuk bakal diantriin di sini sebelum diproses OCR. Redis ringan dan cepet, cocok buat tugas ini
db (PostgreSQL): Database buat nyimpen semua metadata dokumen – judul, tag, correspondent, tanggal, hasil OCR, dan lain-lain. Data dokumen aslinya tetep disimpen di filesystem, bukan di database
webserver (Paperless-ngx): Aplikasi utama yang handle dashboard web, API, dan proses OCR. Ini yang bakal kamu akses lewat browser
ports “8010:8000”: Map port 8000 di container ke port 8010 di host. Artinya kamu akses dashboard lewat http://ip-vps:8010
volumes data dan media: Docker named volumes buat nyimpen data aplikasi dan file dokumen. Pakai named volume biar Docker yang manage dan gak gampang kehapus
volumes ./consume dan ./export: Bind mount ke folder lokal yang tadi kita bikin. Consume buat drop file masuk, export buat backup keluar
depends_on: Mastiin database dan Redis udah jalan duluan sebelum webserver nyala
restart: unless-stopped: Container otomatis nyala lagi kalau VPS di-reboot, kecuali kamu sengaja stop manual

Simpan file dengan Ctrl+O lalu Enter, keluar dari nano dengan Ctrl+X.

Step 3 – Buat File Environment

Masih di folder yang sama, bikin file environment buat konfigurasi Paperless-ngx:

nano docker-compose.env

Paste isi berikut dan sesuaikan nilainya:

PAPERLESS_SECRET_KEY=hasil-dari-openssl-rand-tadi
PAPERLESS_TIME_ZONE=Asia/Jakarta
PAPERLESS_OCR_LANGUAGE=eng+ind
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=ganti-dengan-password-kuat
PAPERLESS_URL=https://dokumen.contoh.com
POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=ganti-password-database-ini

Penjelasan setiap variabel:

PAPERLESS_SECRET_KEY: String acak buat enkripsi session. Pakai hasil dari openssl rand -base64 32 yang udah kamu generate di prasyarat tadi. Jangan pakai string pendek atau gampang ditebak
PAPERLESS_TIME_ZONE: Timezone buat timestamp dokumen. Asia/Jakarta buat WIB, Asia/Makassar buat WITA, Asia/Jayapura buat WIT
PAPERLESS_OCR_LANGUAGE: Bahasa yang dipakai OCR buat baca dokumen. eng buat Inggris, ind buat Indonesia. Pakai eng+ind kalau dokumen kamu campuran dua bahasa. Ini penting banget – kalau salah set, hasil OCR bakal berantakan
PAPERLESS_ADMIN_USER: Username buat login pertama kali ke dashboard
PAPERLESS_ADMIN_PASSWORD: Password admin. Bikin yang kuat, minimal 12 karakter
PAPERLESS_URL: URL lengkap tempat kamu bakal akses dashboard. Harus sama persis dengan domain yang kamu pakai, termasuk https-nya. Kalau ini salah, dashboard bakal nolak request
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD: Kredensial database PostgreSQL. Ganti password-nya dengan yang kuat juga

Simpan file dengan Ctrl+O lalu Enter, keluar dengan Ctrl+X.

Step 4 – Jalankan Container

Sekarang jalanin semua container sekaligus:

docker compose up -d

Docker bakal download tiga image (Redis, PostgreSQL, Paperless-ngx) dan jalanin container-nya di background. Proses pertama kali bisa makan waktu 3-5 menit tergantung kecepatan internet VPS. Setelah semua container jalan, Paperless-ngx butuh waktu tambahan sekitar 1-2 menit buat migrasi database di awal. Jadi jangan buru-buru buka dashboard, tunggu dulu sebentar.

Step 5 – Cek Status Container

Setelah beberapa menit, cek apakah semua container udah jalan dengan bener:

docker compose ps

Kamu harusnya liat tiga container dengan status Up atau healthy:

paperless-ngx-broker-1 (Redis) – status Up
paperless-ngx-db-1 (PostgreSQL) – status Up
paperless-ngx-webserver-1 (Paperless-ngx) – status Up atau healthy

Kalau ada yang statusnya Restarting atau Exit, cek log-nya buat tau penyebabnya:

docker compose logs -f webserver

Flag -f buat follow log secara real-time. Tekan Ctrl+C buat keluar dari mode follow.

Setup Consume Folder dan Auto-Tagging

Buka browser dan akses dashboard Paperless-ngx:

http://ip-vps-kamu:8010

Login pakai username dan password admin yang udah kamu set di file docker-compose.env tadi. Kalau halaman gak mau kebuka, pastiin container webserver udah status healthy (bukan cuma Up) dan port 8010 gak di-block firewall.

Step 7 – Setup Aturan Auto-Tagging

Ini fitur yang bikin Paperless-ngx beda dari sekadar tool OCR biasa. Di dashboard, masuk ke menu Settings > Matching Rules (atau di beberapa versi ada di menu terpisah). Di sini kamu bisa bikin aturan otomatis buat nge-tag dokumen berdasarkan isinya. Contoh aturan yang bisa kamu bikin:

Tagihan Listrik: Kalau isi dokumen mengandung kata “PLN” atau “listrik” atau “kwh”, otomatis dikasih tag “Tagihan” dan correspondent “PLN”
Invoice: Kalau ada kata “invoice” atau “faktur” atau “total pembayaran”, otomatis dikasih tag “Invoice” dan document type “Keuangan”
Kontrak: Kalau ada kata “perjanjian” atau “kontrak” atau “pihak pertama”, otomatis dikasih tag “Legal” dan document type “Kontrak”

Tips: mulai dari beberapa aturan sederhana dulu. Makin banyak dokumen yang udah ke-tag, makin gampang kamu nemuin pola dan bikin aturan yang lebih spesifik. Jangan langsung bikin puluhan aturan di awal, soalnya kamu belum tau pola dokumen kamu yang sebenarnya.

Step 8 – Test Consume Folder

Sekarang test fitur consume folder yang tadi udah di-setup. Dari VPS, copy atau download file PDF ke folder consume:

cp /path/ke/dokumen-test.pdf /opt/paperless-ngx/consume/

Atau kalau mau upload dari laptop, bisa pakai SCP:

scp dokumen-test.pdf user@ip-vps:/opt/paperless-ngx/consume/

Tunggu 30 detik sampai 1 menit. Paperless-ngx bakal otomatis detect file baru di folder consume, jalanin OCR, ekstrak teksnya, dan mindahin ke arsip. Kamu bisa pantau prosesnya lewat log:

docker compose logs -f webserver

Cari baris yang isinya “Consuming” dan “Document added” – itu tandanya dokumen berhasil diproses.

Testing dan Verifikasi

Step 9 – Verifikasi Hasil OCR

Setelah dokumen test berhasil diproses di Step 8, sekarang cek apakah OCR-nya beneran jalan. Buka dashboard Paperless-ngx, kamu harusnya liat dokumen yang baru diproses muncul di halaman utama. Klik dokumen tersebut buat buka detailnya.

Yang perlu dicek:

Content tab: Di sini kamu bisa liat teks hasil OCR. Kalau isinya sesuai sama isi dokumen asli, berarti OCR jalan dengan bener. Kalau hasilnya berantakan atau kosong, kemungkinan setting bahasa OCR-nya salah atau kualitas scan-nya terlalu rendah
Metadata: Cek apakah tanggal, correspondent, dan document type udah ke-assign otomatis (kalau kamu udah bikin matching rules di Step 7)
Tags: Kalau auto-tagging udah di-setup, cek apakah tag yang sesuai udah nempel di dokumen ini

Kalau hasil OCR-nya kurang akurat buat dokumen bahasa Indonesia, pastiin PAPERLESS_OCR_LANGUAGE di file env udah include ind. Kalau dokumen kamu campuran Inggris dan Indonesia, pakai eng+ind.

Step 10 – Test Pencarian Full-Text

Ini momen pembuktian fitur utama Paperless-ngx. Di dashboard, cari kolom pencarian (biasanya di bagian atas). Ketik kata yang kamu tau ada di dalam dokumen test tadi. Misalnya kalau dokumen test-nya tagihan listrik, coba ketik “kwh” atau “PLN”.

Kalau dokumen muncul di hasil pencarian, selamat – full-text search udah berfungsi. Ini artinya semua dokumen yang kamu arsipkan ke depannya bakal bisa dicari berdasarkan isinya, bukan cuma nama file.

Coba juga test dengan beberapa skenario:

Cari kata yang ada di tengah dokumen (bukan di judul)
Cari angka spesifik (misalnya nomor invoice atau nominal pembayaran)
Cari kombinasi kata (misalnya “tagihan januari”)

Kalau semua skenario di atas berhasil, Paperless-ngx kamu udah siap dipakai buat arsip dokumen sehari-hari.

Yang Perlu Diperhatiin Setelah Install Paperless-ngx

Ada beberapa masalah yang sering muncul setelah install. Baca bagian ini biar kamu gak perlu debugging berjam-jam buat masalah yang sebenernya umum.

Dashboard Gak Bisa Diakses Padahal Container Udah Healthy

Ini masalah paling umum. Container udah status healthy tapi pas buka browser gak mau load. Penyebab utamanya biasanya salah satu dari ini:

PAPERLESS_URL gak cocok: Ini penyebab nomor satu. Nilai PAPERLESS_URL di file env harus sama persis dengan URL yang kamu pakai buat akses di browser, termasuk protokol (http/https) dan port-nya. Kalau di env kamu tulis https://dokumen.contoh.com tapi akses lewat http://ip:8010, Paperless-ngx bakal nolak request karena origin-nya beda
Port di-block firewall: Kalau akses lewat IP, pastiin port 8010 terbuka di UFW (sudo ufw allow 8010/tcp) dan di firewall panel provider VPS
Database belum selesai migrasi: Pas pertama kali jalan, Paperless-ngx butuh waktu buat setup database. Tunggu 1-2 menit setelah container up sebelum coba akses dashboard

OCR Gak Jalan atau Hasil Berantakan

Kalau dokumen masuk tapi teks hasil OCR-nya kosong atau gak bisa dibaca, cek beberapa hal ini:

Bahasa OCR salah: Pastiin PAPERLESS_OCR_LANGUAGE udah di-set sesuai bahasa dokumen kamu. Buat dokumen Indonesia, harus ada ind. Buat campuran, pakai eng+ind
Redis gak connect: OCR task diantriin lewat Redis. Kalau Redis container gak jalan atau gak bisa connect, task OCR gak bakal diproses. Cek dengan docker compose logs broker
Kualitas scan rendah: Dokumen yang di-scan dengan resolusi rendah, miring, atau buram bakal bikin OCR kesulitan. Coba scan ulang dengan resolusi minimal 300 DPI dan pastiin dokumen gak miring
RAM gak cukup: OCR itu memory-intensive. Kalau VPS kamu cuma 1GB RAM, proses OCR bisa gagal di tengah jalan. Cek dengan free -h pas OCR lagi jalan

Keamanan Dashboard – Jangan Buka Port Langsung ke Publik

Ini yang paling penting dan sering diabaikan. Dashboard Paperless-ngx isinya dokumen pribadi atau bisnis yang sensitif banget – KTP, kontrak kerja, slip gaji, invoice. Jangan pernah buka port webserver-nya langsung ke publik tanpa proteksi.

Rekomendasi setup keamanan:

Pasang reverse proxy: Taruh Paperless-ngx di belakang Traefik atau Nginx buat handle SSL/HTTPS
Pakai Cloudflare Tunnel: Alternatif yang lebih gampang, pakai Cloudflare Tunnel biar gak perlu buka port sama sekali ke publik
Akses lewat VPN: Kalau cuma kamu yang pakai, akses dashboard lewat Tailscale atau WireGuard biar cuma bisa diakses dari jaringan private
Atur UFW: Kalau gak pakai reverse proxy, minimal atur UFW biar port 8010 cuma bisa diakses dari IP tertentu: sudo ufw allow from IP-KAMU to any port 8010

Jangan Lupa Backup

Paperless-ngx bukan pengganti backup. Semua dokumen kamu disimpen di Docker volume (data dan media). Kalau server bermasalah dan volume hilang, arsip kamu juga ikut hilang. Masukin folder data dan media ke rutinitas backup volume Docker kamu. Atau minimal, jadwalin export berkala lewat fitur export bawaan Paperless-ngx ke folder ./export yang udah kita mount tadi, lalu sync folder itu ke storage external.

Kesimpulan

Buat yang udah capek nyari dokumen satu-satu di folder Google Drive atau tumpukan file scan yang gak terorganisir, Paperless-ngx layak banget buat dicoba. Dengan OCR otomatis, full-text search, dan auto-tagging, semua dokumen kamu jadi bisa dicari dalam hitungan detik berdasarkan isinya – bukan cuma nama file. Dan karena self-hosted, dokumen sensitif kayak KTP, kontrak, atau slip gaji tetep aman di server kamu sendiri.

Tips buat yang baru mulai: jangan langsung migrasiin seluruh arsip fisik kamu sekaligus. Mulai dari satu kategori dokumen dulu, misalnya tagihan bulanan atau invoice. Bikin beberapa matching rules sederhana, lalu lihat hasilnya. Setelah aturan tagging-nya udah ke-tuning dan kamu udah nyaman sama workflow-nya, baru perlahan tambahin kategori dokumen lain.

Yang paling penting, jangan lupa amankan dashboard-nya dan setup backup rutin. Arsip digital yang hilang karena server crash tanpa backup itu lebih nyesek daripada dokumen fisik yang ketumpuk di lemari.

Label: Docker Linux Paperless-ngx Vps