VPS-এ Paperless-ngx সেটআপ করার নিয়ম
Docker Compose ব্যবহার করে VPS-এ Paperless-ngx ইনস্টল করার পূর্ণাঙ্গ গাইড। Postgres কনফিগারেশন, PAPERLESS_URL সেটআপ, OCR ভাষা নির্বাচন এবং HTTPS সিকিউরিটি নিশ্চিত করার উপায় জানুন।
আপনি যা তৈরি করছেন
VPS-এ Paperless-ngx চালালে স্ক্যান করা কাগজের একটি ফোল্ডার অনুসন্ধানযোগ্য archive-এ পরিণত হয়। আপনি একটি PDF watched directory-তে রাখলে server সেটিতে OCR (optical character recognition) চালায়, text extract করে, date ও correspondent অনুমান করে এবং সেটি file করে। ইনস্টলেশনের জন্য চারটি service-সহ একটি Docker Compose file যথেষ্ট। এরপরের সবকিছু configuration-নির্ভর। এই guide-এর বেশিরভাগ অংশ তাই configuration নিয়ে, কারণ install সাধারণত সেখানেই ব্যর্থ হয়। এটি photo library নয়। OCR এবং correspondent অনুমান holiday JPEG-এর folder-এর জন্য কোনো কাজ করে না। তাই সেগুলো ছবির জন্য তৈরি photo server-এ রাখুন এবং Paperless-কে কাগজের নথির জন্য ব্যবহার করুন। Video-এর ক্ষেত্রেও একই নিয়ম প্রযোজ্য। Ripped film-এর collection media server-এ থাকা উচিত, যেখানে 90s-এর rental store-এর মতো সাজানো Jellyfin front end browsing-কে মূল উদ্দেশ্য করে, শুধু search-কে নয়।
Paperless-ngx হলো মূল Paperless project-এর community-maintained fork। এটি free এবং self-hosted। আপনার document disk-এ plain file হিসেবে সংরক্ষণ করে, তাই নিজের archive-এ প্রবেশাধিকার কখনো হারাবেন না। Home box-এর বদলে VPS-এ এটি চালালে home router-এ port না খুলেই যেকোনো স্থান থেকে scan-এ প্রবেশ করা যায়। এটি কাগজের নথি নয় এমন file-এর জন্য private Nextcloud instance-এর সঙ্গেও ভালোভাবে কাজ করে। একই যুক্তি scanner-এ সংযুক্ত desktop-এর ক্ষেত্রেও প্রযোজ্য। কারণ সেই VPS-এ আপনার নিজের RustDesk relay থাকলে router-এ port না খুলেই অন্য স্থান থেকে ওই machine নিয়ন্ত্রণ করতে পারবেন।
স্ট্যাকটি আসলে কী চালায়
অফিশিয়াল compose file চারটি container চালায়। প্রতিটি container কী কাজ করে তা জানলে log পড়া সহজ হয়।
webserver: paperless-ngx image নিজেই। এটি web interface, API, আপনার input folder পর্যবেক্ষণকারী consumer এবং OCR চালানো Celery task worker-গুলো পরিচালনা করে।db: PostgreSQL। এটি metadata, tag, correspondent এবং full-text search index table সংরক্ষণ করে। আপনার PDF এখানে সংরক্ষিত হয় না।broker: Valkey, Redis-compatible key-value store। এটি web process ও worker-গুলোর মধ্যে task queue হিসেবে কাজ করে।gotenbergএবংtika: ঐচ্ছিক, শুধু-tikacompose variant-এ থাকে। এগুলো Office document (.docx,.xlsx,.odt) PDF-এ রূপান্তর করে, যাতে paperless সেগুলো index করতে পারে।
October 2026 অনুযায়ী postgres compose file-এ docker.io/library/postgres:18 ও docker.io/valkey/valkey:9-alpine নির্দিষ্ট করা আছে এবং app-টি ghcr.io/paperless-ngx/paperless-ngx:latest থেকে pull করা হয়।
প্রয়োজনীয়তা
sudoঅ্যাক্সেসসহ একটি Ubuntu 24.04 KVM VPS এবং আগে থেকেই ইনস্টল করা Docker ও Compose plugin। এই অংশটি নতুন হলে VPS-এর জন্য Docker Compose-এর মৌলিক বিষয়গুলো দিয়ে শুরু করে পরে এখানে ফিরে আসুন।- VPS-এর দিকে নির্দেশ করা একটি A record-সহ একটি domain name। যে hostname সম্পর্কে Paperless-কে জানানো হয়নি, সেটিতে HTTPS-এর মাধ্যমে sign-in Paperless গ্রহণ করবে না। তাই এটি আপনি যতটা ভাবছেন, তারও আগে গুরুত্বপূর্ণ।
- প্রকৃত সীমাবদ্ধতা হলো memory। PostgreSQL, Valkey, Granian web server এবং একটি Tesseract OCR worker একই সময়ে চালু থাকলে হালকা ব্যবহারের জন্য 2 GB যথেষ্ট। শত শত scan-এর backlog import করার পরিকল্পনা থাকলে 4 GB দিন। কারণ বড় multi-page PDF-এ OCR চালানোর সময় memory usage হঠাৎ বেড়ে যায় এবং kernel-এর out-of-memory killer worker বন্ধ করে দিতে পারে।
- Disk: আপনার archive দুবার সংরক্ষিত হয়—মূল file এবং OCR করা archive PDF হিসেবে। তাই scan-এর আকারের আনুমানিক দ্বিগুণ storage বরাদ্দ করুন।
অফিসিয়াল compose ফাইলগুলো সংগ্রহ করা
এখানে একটি ইন্টারঅ্যাক্টিভ ইনস্টলার রয়েছে:
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"এটি আপনাকে কিছু প্রশ্ন করবে এবং আপনার জন্য ফাইলগুলো তৈরি করে দেবে। তবে হাতে কলমে কাজ করা মানে চারটি কমান্ড চালানো, যা আপনাকে সার্ভারের প্রতিটি ফাইলের অবস্থান সম্পর্কে পরিষ্কার ধারণা দেবে। রক্ষণাবেক্ষণের জন্য এটিই সবচেয়ে ভালো পদ্ধতি।
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এর ভ্যারিয়েন্টগুলো একই ডিরেক্টরিতে থাকে: docker-compose.sqlite.yml, docker-compose.mariadb.yml এবং প্রতিটির একটি -tika সংস্করণ। নতুন ইনস্টলেশনের জন্য postgres বেছে নিন। অল্প কয়েকশ ডকুমেন্টের জন্য SQLite ঠিক আছে, কিন্তু PostgreSQL-এর তুলনায় এর ফুল-টেক্সট সার্চ ইনডেক্স অনেক আগেই ধীর হয়ে যায়।
.env ফাইলটিতে একটি মাত্র লাইন থাকে, COMPOSE_PROJECT_NAME=paperless। এই নামটি প্রতিটি কন্টেইনার এবং ভলিউমের প্রিফিক্স হিসেবে ব্যবহৃত হয়। তাই এটি মুছে ফেলবেন না, অন্যথায় docker compose down -v কেন আপনার ডেটা খুঁজে পাচ্ছে না তা নিয়ে সমস্যায় পড়তে পারেন।
প্রথমবার চালুর আগে docker-compose.env কনফিগার করুন
দুটি সেটিংস ঐচ্ছিক নয়। প্রকল্পের নথিতে দেওয়া কমান্ড দিয়ে secret key তৈরি করুন:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"এরপর 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-এ আক্ষরিক মান হিসেবে change-me থাকে। এটি session token-এ স্বাক্ষর করে। বর্তমান release-গুলো এই placeholder-কে সেট না করা মান হিসেবে গণ্য করে। key অনুপস্থিত, ফাঁকা বা এখনও change-me থাকলে paperless চালু হতে অস্বীকার করে। তাই এটি প্রতিস্থাপন না করা পর্যন্ত stack চালু হবে না। প্রথমবার চালুর আগেই এটি সেট করুন, কারণ পরে পরিবর্তন করলে সব ব্যবহারকারী sign out হয়ে যাবেন।
PAPERLESS_URL সেটিংসটি আপনার প্রায় এক ঘণ্টা সময় বাঁচায়। Paperless একটি Django application। Django Host header এবং sign-in form-এর ক্ষেত্রে browser যে origin জানায়, দুটিই পরীক্ষা করে। PAPERLESS_URL সেট করলে এটি আপনার address-টি স্বয়ংক্রিয়ভাবে ALLOWED_HOSTS, CORS_ALLOWED_HOSTS এবং CSRF_TRUSTED_ORIGINS-এ যোগ করে। এটি ফাঁকা রাখলে এবং box-এর জন্য একটি domain নির্ধারণ করলে sign-in page এখনও load হবে, কারণ PAPERLESS_ALLOWED_HOSTS-এর default মান *। কিন্তু HTTPS-এর মাধ্যমে form submit ব্যর্থ হবে এবং CSRF verification failed. Request aborted. দেখাবে, কারণ আপনার domain trusted origin নয়। এটি trailing slash ও path ছাড়া লিখুন।
USERMAP_UID এবং USERMAP_GID নির্ধারণ করে container কোন user হিসেবে চলবে। নিজের account-এর সঙ্গে এগুলোর মিল রাখুন। id -u এবং id -g চালিয়ে account-এর মান পরীক্ষা করুন। মান দুটি না মিললে consume folder-এ কপি করা file-গুলো consumer পড়তে পারবে না। তখন import-এর বদলে log-এ permission error দেখা যাবে।
স্ট্যাক চালু করুন এবং প্রথম ব্যবহারকারী তৈরি করুন
docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webservercreatesuperuser একটি username, একটি email এবং একটি password চায়। কোনো default login নেই। এই ধাপ এড়িয়ে গেলে, যে ব্যক্তি প্রথমে web interface খুলবে তাকে superuser তৈরি করতে বলা হবে। port 8000 তখনও Internet-এ খোলা থাকলে সেই ব্যক্তি আপনি নাও হতে পারেন। তাই shell থেকেই সঙ্গে সঙ্গে account তৈরি করুন। Browser-এ চেষ্টা করার আগে log-এ server port 8000-এ listening করছে—এমন line আসা পর্যন্ত অপেক্ষা করুন। প্রথমবার start করার সময় database migration-ও চলে। এতে 1 বা 2 মিনিট সময় লাগতে পারে।
Domain ব্যবহার করার আগে স্থানীয়ভাবে পরীক্ষা করুন:
curl -I http://127.0.0.1:8000একটি 302 redirect থেকে /accounts/login/-এ যাওয়া বোঝায় যে stack সুস্থভাবে চলছে।
এটির সামনে HTTPS দিন
ডিফল্ট Compose ফাইলে 8000:8000 প্রকাশ করা হয়, যা সব interface-এ bind হয়। কোনো public VPS-এ এর ফলে ঠিকানাটি খুঁজে পাওয়া যে কেউ পুরো document archive plain HTTP-তে দেখতে পারে। শুধু loopback-এ bind করতে port line-টি পরিবর্তন করুন:
ports:
- "127.0.0.1:8000:8000"এরপর reverse proxy-তে TLS (transport layer security) termination করুন এবং অনুরোধ 127.0.0.1:8000-এ forward করুন। সার্ভারে এটিই একমাত্র app হলে ACME (automatic certificate management environment) client-সহ যেকোনো proxy ব্যবহার করা যাবে। একই certificate setup-এর পেছনে একাধিক container চালালে একাধিক Docker Compose app-এর জন্য Traefik reverse proxy pattern অনুসরণ করুন এবং কোনো published port ছাড়াই webserver service-টিকে proxy network-এ যুক্ত করুন।
যে proxy-ই ব্যবহার করুন, HTTPS setup-এ login form-এর origin check-ই সাধারণত সমস্যা তৈরি করে। PAPERLESS_PROXY_SSL_HEADER সেট না করলে Paperless X-Forwarded-Proto উপেক্ষা করে। এটি default হিসেবে বন্ধ থাকে। ফলে Django proxied প্রতিটি request-কে plain HTTP হিসেবে ধরে। আপনার browser যে https:// origin পাঠায়, সেটি trusted হিসেবে তালিকাভুক্ত থাকলেই কেবল গ্রহণ করা হয়। browser-এ লেখা সঠিক https:// address-এ PAPERLESS_URL সেট করলেই address-টি ওই তালিকায় যুক্ত হয়। এটি না থাকলে দেখতে সঠিক একটি page-এ CSRF verification failed. Request aborted. দেখা যাবে।
এছাড়া proxy-এর upload size limit বাড়ান। 40 MB-এর scan এমন কোনো proxy দিয়ে পাঠালে, যেটি request body 1 MB-এ সীমাবদ্ধ রাখে, paperless request পাওয়ার আগেই সেটি প্রত্যাখ্যান করবে এবং browser একটি সাধারণ upload failure দেখাবে।
consume directory কীভাবে কাজ করে
compose fileটি compose directory-এর ./consume-কে container-এর মধ্যে bind-mount করে। সেখানে রাখা যেকোনো file import করার পর folder থেকে মুছে ফেলা হয়, কারণ fileটি এখন paperless-এর ব্যবস্থাপনায় media volume-এ থাকে।
cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserverconsumer-কে filename শনাক্ত করে OCR চালাতে এবং document যোগ হয়েছে জানিয়ে একটি line দিয়ে কাজ শেষ করতে দেখা উচিত। এক পৃষ্ঠার scan-এর ক্ষেত্রে পুরো প্রক্রিয়াটি কয়েক সেকেন্ড লাগে। বড় document-এর ক্ষেত্রে এক মিনিট বা তার বেশি লাগতে পারে।
দুটি setting file খোঁজার পদ্ধতি পরিবর্তন করে। PAPERLESS_CONSUMER_RECURSIVE=true paperless-কে subfolder-এ খুঁজতে বাধ্য করে। PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true প্রতিটি subfolder-এর নামকে tag হিসেবে ব্যবহার করে। তাই consume/invoices/2026/-এ একটি file রাখলে সেটিতে invoices এবং 2026 tag যোগ হয়। এর চেয়ে সহজ filing system তৈরি করা কঠিন।
Detection প্রক্রিয়াটি এর অন্য অংশ। ডিফল্টভাবে PAPERLESS_CONSUMER_POLLING_INTERVAL হলো 0। এর অর্থ, paperless native filesystem notification ব্যবহার করে, যা সঙ্গে সঙ্গে কার্যকর হয়। Network filesystem-এ এই notification নির্ভরযোগ্য নয়। আপনার consume folder যদি NFS বা SMB share হয়, যাতে কোনো network scanner সেখানে file লিখতে পারে, তাহলে file শনাক্ত না হয়ে সেখানে পড়ে থাকতে পারে। এর সমাধান হলো interval-কে positive সংখ্যক seconds-এ সেট করা, যাতে paperless notification-এর বদলে folder scan করে।
OCR-এর ভাষা এবং সেগুলোর খরচ
PAPERLESS_OCR_LANGUAGE-এ তিন অক্ষরের Tesseract code দিতে হয়। ডিফল্ট মান হলো eng। ভাষাগুলো plus চিহ্ন দিয়ে একত্র করুন, যেমন deu+eng। এরপর Tesseract প্রতিটি page-এ তালিকাভুক্ত সব ভাষা ব্যবহার করে কাজ করে। তাই প্রতিটি অতিরিক্ত ভাষা প্রতিটি scan-এ CPU time বাড়ায়। shared-vCPU VPS-এ এর ফলে একটি scan শেষ হতে দশ সেকেন্ডের বদলে এক মিনিট লাগতে পারে। আপনার নথি যেসব ভাষায় লেখা, শুধু সেসব ভাষা তালিকাভুক্ত করুন।
এই image-এ English, German, Italian, Spanish এবং French অন্তর্ভুক্ত আছে। অন্য কোনো ভাষার জন্য সেই ভাষাটি PAPERLESS_OCR_LANGUAGES-এ space-separated list হিসেবে যোগ করুন, যেমন PAPERLESS_OCR_LANGUAGES=tur ces, এবং restart করুন। container startup-এর সময় Tesseract data pack download করে। তাই পরিবর্তনের পর প্রথম boot-এ বেশি সময় লাগে।
ডেটাবেস ও মিডিয়ার ব্যাকআপ নিন
PostgreSQL চালু থাকা অবস্থায় Docker volume কপি করলে এমন একটি ব্যাকআপ তৈরি হতে পারে, যা পরে restore করা যাবে না। Paperless-এর নিজস্ব exporter রয়েছে। এটি নথি এবং সব metadata-এর একটি JSON manifest ./export bind mount-এ লিখে:
docker compose exec -T webserver document_exporter ../export --delete --no-progress-bar--delete বর্তমান কোনো নথির সঙ্গে আর মেলে না এমন exported file মুছে দেয়। ফলে folder-টি চিরদিন বড় হতে থাকে না; একটি mirror হিসেবে থাকে। cron থেকে এটি চালানোর সময় --no-progress-bar output পরিষ্কার রাখে, এবং -T Compose-কে এমন terminal চাইতে বাধা দেয়, যা cron-এর নেই।
নতুন stack-এ একই folder ব্যবহার করে restore করা document_importer। অর্থাৎ export directory-টিই আপনাকে নিরাপদে সংরক্ষণ করতে হবে। আপনার VPS থেকে encrypted, deduplicated restic backups ব্যবহার করে নির্ধারিত সময়ে এটি offsite-এ পাঠান। আগে export চালান, যাতে restic কখনও অর্ধেক লেখা archive capture না করে।
export/manifest.json আছে কি না এবং file count interface-এ দেখানো document count-এর সঙ্গে মেলে কি না যাচাই করে একটি backup পরীক্ষা করুন। যে backup কখনও তালিকাভুক্ত করে দেখা হয়নি, সেটি backup নয়। রাতে চলা export নীরবে ব্যর্থ হতে শুরু করলে পরিস্থিতি আরও খারাপ হয়। তাই cron job-এর exit status আপনার নিজস্ব ntfy server-এ পাঠান। তাহলে restore করার দিন নয়, export ব্যর্থ হওয়ার সপ্তাহেই বিষয়টি জানতে পারবেন।
FAQ
প্রতিটি page-এ domain নির্দেশ করার পর "Bad Request (400)" দেখায় কেন?
Stock file ব্যবহার করলে এমন হওয়ার কথা নয়, কারণ PAPERLESS_ALLOWED_HOSTS-এর default মান হলো *। Container log-এ DisallowedHost-সহ একটি 400 বার্তার অর্থ হলো, PAPERLESS_ALLOWED_HOSTS এমন একটি তালিকায় সেট করা হয়েছে যেখানে আপনার domain নেই। docker-compose.env-এ PAPERLESS_URL=https://paperless.example.com সেট করুন; শেষে slash দেবেন না। তাহলে paperless ওই hostname-টি তালিকায় যোগ করবে। অথবা PAPERLESS_ALLOWED_HOSTS লাইনটি সরিয়ে দিন। এরপর container পুনরায় তৈরি করতে docker compose up -d চালান। শুধু env file সম্পাদনা করলে কোনো পরিবর্তন হবে না, কারণ চলমান container শুরু হওয়ার সময় পাওয়া environment-ই ধরে রাখে।
consume folder-এ একটি PDF রাখার পরও কিছু ঘটল না। সমস্যা কী?
প্রথমে docker compose logs webserver পরীক্ষা করুন। Permission error-এর অর্থ হলো USERMAP_UID এবং USERMAP_GID file-টির মালিক account-এর সঙ্গে মেলে না। তাই সেগুলো ঠিক করে container পুনরায় তৈরি করুন। Log-এ একেবারেই কোনো line না থাকলে বুঝতে হবে file event পৌঁছায়নি। Network share-এ এমন হয়, কারণ native filesystem notification সেখানে নির্ভরযোগ্য নয়। PAPERLESS_CONSUMER_POLLING_INTERVAL-কে 30-এর মতো কোনো মানে সেট করুন। তাহলে paperless-এর পরিবর্তে প্রতি 30 সেকেন্ডে folder scan করবে।
PostgreSQL-এর পরিবর্তে SQLite দিয়ে paperless-ngx চালাতে পারি?
হ্যাঁ, docker-compose.sqlite.yml সমর্থিত এবং এটি কম memory ব্যবহার করে। তাই ছোট VPS-এর জন্য এটি উপযোগী। Archive বড় হওয়ার সঙ্গে tradeoff দেখা যায়: হাজার হাজার document হলে full-text search এবং bulk tag edit লক্ষণীয়ভাবে ধীর হয়ে যায়। পরে migration করতে export এবং import দুটিই প্রয়োজন হবে। তাই archive বাড়তে থাকবে বলে আশা করলে এখনই PostgreSQL বেছে নিন।
Scan archive-এর জন্য বাস্তবে কত disk space প্রয়োজন?
আপনার source file-এর আকারের আনুমানিক দ্বিগুণ। Paperless মূল file অপরিবর্তিত রাখে এবং searchable text layer-সহ দ্বিতীয় একটি OCR করা PDF সংরক্ষণ করে। এর সঙ্গে ছোট thumbnail-ও থাকে। Text-only scan-এর আকার 200 KB হলে সেটি ছোটই থাকে। দীর্ঘ contract-এর 30 MB colour scan প্রায় 60 MB জায়গা নেয়। Export directory একই disk-এ রাখলে সেটির জায়গাও যোগ করুন। তখন একই archive disk-এ প্রায় তিন গুণ জায়গা নেবে।
Tika এবং Gotenberg container কি প্রয়োজন?
শুধু Word, Excel বা OpenDocument file আপনার PDF-এর পাশাপাশি index করতে চাইলে এগুলো প্রয়োজন। এগুলো ওই format-গুলোকে PDF-এ রূপান্তর করে, যাতে paperless সেগুলোতে OCR চালিয়ে search করতে পারে। এগুলো চালু থাকা আরও 2টি container এবং কয়েকশো megabyte memory যোগ করে। তাই ছোট server-এ এগুলো বাদ দিন, যদি আপনার সংরক্ষণ করা সব file আগে থেকেই PDF বা image হয়।