Paperless-ngx di VPS: Arsip Dokumen dengan Docker
Panduan menjalankan paperless-ngx di VPS dengan Docker Compose, termasuk stack Postgres resmi, PAPERLESS_URL, folder consume, bahasa OCR, HTTPS, dan pencadangan.
Yang akan Anda bangun
Paperless-ngx pada VPS mengubah folder berisi dokumen hasil pemindaian menjadi arsip yang dapat ditelusuri. Anda cukup menaruh PDF di direktori yang dipantau. Server kemudian menjalankan OCR (optical character recognition) pada file tersebut, mengekstrak teks, memperkirakan tanggal dan koresponden, lalu mengarsipkannya. Instalasinya menggunakan satu file Docker Compose dengan empat service. Setelah itu, semuanya berupa konfigurasi. Panduan ini menghabiskan sebagian besar isinya untuk konfigurasi karena di situlah instalasi sering gagal. Paperless-ngx bukan pustaka foto. OCR dan perkiraan koresponden tidak berguna untuk folder berisi JPEG liburan. Simpan file seperti itu di server foto yang dibuat khusus untuknya, dan gunakan Paperless-ngx untuk dokumen. Hal yang sama berlaku untuk video. Koleksi film hasil ripping sebaiknya disimpan di media server. Di sana, sesuatu seperti frontend Jellyfin yang dibuat menyerupai toko penyewaan tahun 90-an menjadikan penelusuran sebagai tujuan utama, bukan pencarian.
Paperless-ngx adalah fork komunitas yang masih dipelihara dari proyek Paperless asli. Software ini gratis, dapat di-host sendiri, dan menyimpan dokumen sebagai file biasa di disk. Dengan demikian, Anda tidak pernah kehilangan akses ke arsip milik sendiri. Menjalankannya pada VPS, bukan komputer di rumah, membuat hasil pemindaian dapat diakses dari mana saja tanpa membuka port pada router rumah. Paperless-ngx juga cocok dipadukan dengan instance Nextcloud privat untuk file yang bukan dokumen. Logika yang sama berlaku untuk desktop yang terhubung ke scanner Anda. Relay RustDesk milik Anda sendiri pada VPS tersebut memungkinkan Anda mengendalikan komputer itu dari lokasi lain tanpa membuka akses pada router.
Komponen yang sebenarnya dijalankan oleh stack
File compose resmi menjalankan empat container. Memahami fungsi masing-masing container akan memudahkan pembacaan log.
webserver: image paperless-ngx itu sendiri. Image ini menjalankan antarmuka web, API, consumer yang memantau folder input Anda, serta worker task Celery yang menjalankan OCR.db: PostgreSQL. Komponen ini menyimpan metadata, tag, koresponden, dan tabel indeks pencarian teks lengkap. Komponen ini tidak menyimpan file PDF Anda.broker: Valkey, penyimpanan key-value yang kompatibel dengan Redis. Komponen ini menjadi antrean task antara proses web dan worker.gotenbergdantika: opsional, hanya tersedia dalam varian compose-tika. Komponen ini mengonversi dokumen Office (.docx,.xlsx,.odt) menjadi PDF agar paperless dapat mengindeksnya.
Per Oktober 2026, file compose postgres menetapkan versi docker.io/library/postgres:18 dan docker.io/valkey/valkey:9-alpine, serta mengambil aplikasi dari ghcr.io/paperless-ngx/paperless-ngx:latest.
Prasyarat
- VPS KVM Ubuntu 24.04 dengan akses sudo, serta Docker dan plugin Compose yang sudah terpasang. Jika bagian ini masih baru bagi Anda, mulai dengan dasar-dasar Docker Compose untuk VPS lalu kembali ke sini.
- Nama domain dengan A record yang mengarah ke VPS. Paperless tidak akan menerima login melalui HTTPS pada hostname yang belum dikonfigurasikan, jadi hal ini perlu diperhatikan lebih awal.
- Memori adalah kendala utama. PostgreSQL, Valkey, web server Granian, dan worker OCR Tesseract yang berjalan bersamaan dapat menggunakan 2 GB untuk penggunaan ringan. Gunakan 4 GB jika Anda berencana mengimpor ratusan hasil pemindaian, karena OCR pada PDF besar dengan banyak halaman dapat menyebabkan lonjakan penggunaan memori yang membuat worker dihentikan oleh kernel karena kehabisan memori.
- Disk: arsip Anda disimpan dua kali, yaitu file asli dan PDF arsip hasil OCR. Jadi, siapkan kapasitas kira-kira dua kali ukuran hasil pemindaian Anda.
Dapatkan file compose resmi
Tersedia installer interaktif:
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"Installer ini mengajukan beberapa pertanyaan lalu menulis file untuk Anda. Jika dilakukan secara manual, prosesnya hanya memerlukan empat perintah. Anda juga akan mengetahui lokasi setiap file, yang penting untuk server yang akan Anda pelihara.
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/.envSemua varian berada di direktori yang sama: docker-compose.sqlite.yml, docker-compose.mariadb.yml, dan versi -tika untuk masing-masing varian. Pilih postgres untuk instalasi baru. SQLite cukup untuk beberapa ratus dokumen, tetapi indeks pencarian teks lengkap menjadi lambat jauh sebelum PostgreSQL.
File .env berisi satu baris, COMPOSE_PROJECT_NAME=paperless. Nama tersebut menjadi awalan untuk setiap container dan volume. Jangan menghapusnya lalu bingung ketika docker compose down -v tidak dapat menemukan data Anda.
Konfigurasikan docker-compose.env sebelum start pertama
Dua pengaturan wajib diisi. Buat secret key dengan perintah yang didokumentasikan oleh proyek:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"Kemudian edit 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=1000PAPERLESS_SECRET_KEY disertakan dengan nilai literal change-me. Nilai ini digunakan untuk menandatangani token sesi, dan rilis saat ini menganggap placeholder tersebut belum diatur: paperless menolak untuk start jika key belum diisi, kosong, atau masih berupa change-me. Karena itu, stack tidak akan berjalan sampai Anda menggantinya. Tetapkan sebelum start pertama karena perubahan setelahnya akan mengeluarkan semua pengguna dari sesi mereka.
PAPERLESS_URL adalah pengaturan yang dapat menghemat waktu hingga satu jam. Paperless adalah aplikasi Django, dan Django memeriksa header Host serta, pada formulir sign-in, origin yang dilaporkan browser. Tetapkan PAPERLESS_URL, dan aplikasi akan menambahkan alamat Anda ke ALLOWED_HOSTS, CORS_ALLOWED_HOSTS, dan CSRF_TRUSTED_ORIGINS secara otomatis. Jika dibiarkan kosong dan Anda mengarahkan domain ke server, halaman sign-in tetap dimuat karena PAPERLESS_ALLOWED_HOSTS secara default bernilai *. Namun, pengiriman formulir melalui HTTPS gagal dengan CSRF verification failed. Request aborted. karena domain Anda bukan origin tepercaya. Tulis nilainya tanpa trailing slash dan tanpa path.
USERMAP_UID dan USERMAP_GID menentukan user yang digunakan container saat berjalan. Samakan nilainya dengan akun Anda sendiri, yang dapat diperiksa menggunakan id -u dan id -g. Jika tidak sama, file yang Anda salin ke folder consume tidak dapat dibaca oleh consumer, dan log akan menampilkan permission error, bukan melakukan import.
Mulai stack dan buat pengguna pertama
docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webservercreatesuperuser meminta username, email, dan password. Tidak ada login default. Jika langkah ini dilewati, antarmuka web akan meminta siapa pun yang membukanya terlebih dahulu untuk membuat superuser. Selama port 8000 masih terbuka ke Internet, orang tersebut mungkin bukan Anda. Karena itu, segera buat akun dari shell. Tunggu baris log yang menyatakan bahwa server sedang listening pada port 8000 sebelum mencoba membukanya melalui browser. Pada start pertama, sistem juga menjalankan migrasi database. Proses ini memerlukan waktu satu atau dua menit.
Periksa secara lokal sebelum menggunakan domain:
curl -I http://127.0.0.1:8000Redirect 302 ke /accounts/login/ berarti stack berjalan normal.
Pasang HTTPS di depannya
File Compose bawaan memublikasikan 8000:8000, yang mengikat ke semua interface. Pada VPS publik, konfigurasi ini menyajikan seluruh arsip dokumen melalui HTTP biasa kepada siapa pun yang menemukan alamatnya. Ubah baris port agar hanya mengikat ke loopback:
ports:
- "127.0.0.1:8000:8000"Selanjutnya, lakukan terminasi TLS (transport layer security) pada reverse proxy dan teruskan koneksi ke 127.0.0.1:8000. Jika ini satu-satunya aplikasi pada server, proxy apa pun yang memiliki klien ACME (automatic certificate management environment) dapat digunakan. Jika Anda menjalankan beberapa container di balik satu konfigurasi sertifikat, ikuti pola reverse proxy Traefik untuk beberapa aplikasi Docker Compose dan sambungkan service webserver ke jaringan proxy tanpa port yang dipublikasikan sama sekali.
Apa pun proxy yang digunakan, pemeriksaan origin pada formulir login adalah bagian yang sering menyebabkan konfigurasi HTTPS gagal. Paperless mengabaikan X-Forwarded-Proto kecuali Anda menetapkan PAPERLESS_PROXY_SSL_HEADER, yang secara default dinonaktifkan. Akibatnya, Django memperlakukan setiap request yang diteruskan proxy sebagai HTTP biasa, dan origin https:// yang dikirim browser hanya diterima jika tercantum sebagai origin tepercaya. Menetapkan PAPERLESS_URL ke alamat https:// yang sama persis dengan yang Anda ketik di browser akan memasukkannya ke daftar tersebut. Tanpa pengaturan ini, Anda akan mendapatkan CSRF verification failed. Request aborted. pada halaman yang tampak benar.
Naikkan juga batas ukuran upload pada proxy. Scan berukuran 40 MB yang melewati proxy dengan batas body 1 MB akan ditolak sebelum diterima oleh paperless, dan browser hanya menampilkan kegagalan upload umum.
Cara kerja direktori consume
File compose melakukan bind mount ./consume dari direktori compose ke dalam container. Semua file yang Anda tempatkan di sana akan diimpor lalu dihapus dari folder tersebut, karena file itu kini disimpan di volume media yang dikelola oleh paperless.
cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserverAnda akan melihat consumer mengambil nama file, menjalankan OCR, lalu selesai dengan baris yang melaporkan bahwa dokumen telah ditambahkan. Seluruh proses ini berlangsung dalam hitungan detik untuk hasil pemindaian satu halaman dan dapat memerlukan waktu satu menit atau lebih untuk dokumen yang panjang.
Dua pengaturan mengubah cara file ditemukan. PAPERLESS_CONSUMER_RECURSIVE=true membuat paperless mencari di subfolder, sedangkan PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true mengubah setiap nama subfolder menjadi tag. Dengan demikian, file yang ditempatkan di consume/invoices/2026/ akan diberi tag invoices dan 2026. Itulah sistem pengarsipan termurah yang dapat Anda buat.
Deteksi adalah bagian lainnya. Secara default, PAPERLESS_CONSUMER_POLLING_INTERVAL bernilai 0, yang berarti paperless menggunakan notifikasi filesystem native dan notifikasi tersebut dipicu segera. Notifikasi ini tidak andal pada filesystem jaringan. Jika folder consume Anda merupakan share NFS atau SMB agar network scanner dapat menulis ke sana, file dapat berada di folder tanpa terdeteksi. Solusinya adalah menetapkan interval ke jumlah detik positif agar paperless memindai folder tersebut.
Bahasa OCR dan biayanya
PAPERLESS_OCR_LANGUAGE menerima kode Tesseract tiga huruf, dengan eng sebagai nilai default. Gabungkan beberapa bahasa dengan tanda plus, seperti pada deu+eng. Tesseract kemudian memproses setiap halaman menggunakan semua bahasa yang dicantumkan. Karena itu, setiap bahasa tambahan menambah waktu CPU pada setiap pemindaian. Pada VPS dengan vCPU bersama, perbedaannya dapat berupa pemindaian yang selesai dalam sepuluh detik atau baru selesai dalam satu menit. Cantumkan hanya bahasa yang benar-benar digunakan dalam dokumen Anda.
Image tersebut menyertakan bahasa Inggris, Jerman, Italia, Spanyol, dan Prancis. Untuk bahasa lain, tambahkan bahasa tersebut ke PAPERLESS_OCR_LANGUAGES sebagai daftar yang dipisahkan spasi, misalnya PAPERLESS_OCR_LANGUAGES=tur ces, lalu lakukan restart. Container mengunduh paket data Tesseract saat startup, sehingga boot pertama setelah perubahan tersebut akan berlangsung lebih lama.
Cadangkan database dan media
Menyalin volume Docker saat PostgreSQL masih berjalan menghasilkan cadangan yang mungkin tidak dapat dipulihkan. Paperless menyediakan exporter bawaan yang menulis dokumen beserta manifest JSON berisi semua metadata ke bind mount ./export:
docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar--delete menghapus file hasil ekspor yang tidak lagi cocok dengan dokumen saat ini, sehingga folder tersebut tetap menjadi mirror dan tidak terus membesar. --no-progress-bar menjaga output tetap bersih saat proses ini dijalankan oleh cron, sedangkan -T mencegah Compose meminta terminal yang tidak tersedia bagi cron.
Pemulihan dilakukan dengan document_importer terhadap folder yang sama pada stack baru. Artinya, Anda hanya perlu menjaga direktori ekspor tersebut tetap aman. Kirim direktori itu ke lokasi di luar server secara terjadwal menggunakan cadangan restic terenkripsi dan deduplikasi dari VPS Anda, lalu jalankan ekspor terlebih dahulu agar restic tidak pernah menangkap arsip yang belum selesai ditulis.
Verifikasi cadangan dengan memeriksa keberadaan export/manifest.json dan memastikan jumlah file sesuai dengan jumlah dokumen pada antarmuka. Cadangan yang belum pernah diuji dengan pencacahan bukanlah cadangan. Ekspor setiap malam yang diam-diam mulai gagal bahkan lebih berisiko. Karena itu, minta cron job mengirim status keluarnya ke server ntfy Anda sendiri agar Anda mengetahui kegagalan pada minggu terjadinya, bukan pada hari saat pemulihan diperlukan.
FAQ
Mengapa setiap halaman mengembalikan "Bad Request (400)" setelah domain diarahkan ke sana?
Dengan file bawaan, hal itu seharusnya tidak terjadi karena PAPERLESS_ALLOWED_HOSTS secara default bernilai *. 400 dengan DisallowedHost dalam log container berarti PAPERLESS_ALLOWED_HOSTS telah diatur ke daftar yang tidak mencantumkan domain Anda. Atur PAPERLESS_URL=https://paperless.example.com di docker-compose.env tanpa garis miring di akhir, lalu paperless menambahkan hostname tersebut ke dalam daftar, atau hapus baris PAPERLESS_ALLOWED_HOSTS. Kemudian jalankan docker compose up -d untuk membuat ulang container. Mengedit file env saja tidak berpengaruh karena container yang sedang berjalan tetap menggunakan environment saat container tersebut dijalankan.
Saya menaruh PDF di folder consume, tetapi tidak terjadi apa-apa. Apa masalahnya?
Periksa docker compose logs webserver terlebih dahulu. Error permission berarti USERMAP_UID dan USERMAP_GID tidak sesuai dengan akun pemilik file, jadi perbaiki keduanya lalu buat ulang container. Jika sama sekali tidak ada baris log, berarti event file tidak pernah diterima. Hal ini terjadi pada network share karena notifikasi filesystem native tidak dapat diandalkan di sana. Atur PAPERLESS_CONSUMER_POLLING_INTERVAL ke nilai seperti 30 agar paperless memindai folder setiap 30 detik.
Apakah paperless-ngx dapat dijalankan dengan SQLite sebagai pengganti PostgreSQL?
Ya, docker-compose.sqlite.yml didukung dan menggunakan lebih sedikit memori, sehingga sesuai untuk VPS kecil. Kekurangannya mulai terlihat ketika arsip bertambah besar: pencarian full-text dan pengeditan tag secara massal melambat secara nyata saat jumlah dokumen mencapai ribuan. Migrasi di kemudian hari memerlukan export dan import, jadi pilih PostgreSQL sekarang jika arsip diperkirakan terus bertambah.
Berapa banyak disk yang sebenarnya diperlukan untuk arsip hasil pemindaian?
Kira-kira dua kali ukuran file sumber. Paperless menyimpan file asli tanpa perubahan dan file PDF kedua yang telah diproses OCR dengan lapisan teks yang dapat dicari, serta thumbnail berukuran kecil. Hasil pemindaian teks saja berukuran 200 KB tetap kecil. Hasil pemindaian berwarna berukuran 30 MB untuk kontrak panjang akan menggunakan sekitar 60 MB. Tambahkan direktori export jika disimpan pada disk yang sama. Dengan demikian, arsip yang sama akan menggunakan ruang disk tiga kali lipat.
Apakah saya memerlukan container Tika dan Gotenberg?
Hanya jika Anda ingin file Word, Excel, atau OpenDocument diindeks bersama PDF. Keduanya mengonversi format tersebut menjadi PDF agar paperless dapat melakukan OCR dan pencarian. Keduanya juga menambahkan dua container yang terus berjalan dan penggunaan memori beberapa ratus megabyte. Jadi, jangan gunakan keduanya pada server kecil jika semua file yang Anda arsipkan sudah berupa PDF atau gambar.