آموزش نصب Stirling PDF روی VPS با Docker

اگر می‌خواهید ابزارهای ویرایش PDF را بدون آپلود فایل روی سایت‌های ناشناس در اختیار خودتان یا اعضای تیم قرار دهید، Stirling PDF یکی از گزینه‌های کاربردی برای راه‌اندازی روی VPS است. با نصب Stirling PDF روی یک سرور لینوکسی می‌توانید از طریق مرورگر به ابزارهایی مثل ادغام و جداسازی PDF، فشرده‌سازی، تبدیل فرمت، OCR، امضا، چرخاندن صفحات، حذف صفحات و بسیاری از عملیات دیگر دسترسی داشته باشید.

در این آموزش، Stirling PDF را روی Ubuntu VPS با Docker Compose نصب می‌کنیم، دسترسی عمومی مستقیم به پورت برنامه را می‌بندیم، ورود کاربری را فعال نگه می‌داریم و در ادامه روش اتصال دامنه و HTTPS با Nginx را هم توضیح می‌دهیم. مسیر آموزش از یک سرور نسبتاً خام شروع می‌شود و در پایان یک سرویس قابل استفاده در مرورگر خواهید داشت.

Stirling PDF چیست و نصب آن روی VPS چه فایده‌ای دارد؟

Stirling PDF یک مجموعه ابزار PDF با امکان Self-Hosting است. به‌جای اینکه برای هر عملیات، فایل سند را به یک وب‌سایت عمومی ارسال کنید، رابط وب Stirling PDF روی سرور خودتان اجرا می‌شود و کاربران مجاز از طریق مرورگر به آن متصل می‌شوند.

این مدل برای شرکت‌ها، تیم‌های اداری، افرادی که زیاد با فایل PDF کار می‌کنند یا کسانی که می‌خواهند یک ابزار PDF شخصی همیشه در دسترس داشته باشند مناسب است. با این حال، Self-Hosted بودن به این معنی نیست که امنیت به‌صورت خودکار حل شده است؛ اگر سرویس را عمومی می‌کنید باید ورود کاربری، HTTPS، به‌روزرسانی و دسترسی شبکه را جدی بگیرید.

پیش‌نیازهای نصب Stirling PDF روی VPS

مستندات رسمی برای استقرار Production حداقل ۲ گیگابایت RAM، مقدار پیشنهادی ۴ گیگابایت RAM و حدود ۱۰ گیگابایت فضای دیسک را مطرح می‌کنند. مقدار واقعی مصرف منابع به نوع عملیات، اندازه فایل‌ها، OCR، تبدیل اسناد و تعداد کاربران هم‌زمان بستگی دارد.

برای ادامه به دسترسی SSH با کاربری دارای مجوز sudo، یک IP عمومی و در صورت استفاده از دامنه، دسترسی به مدیریت DNS نیاز دارید.

مرحله ۱: اتصال به VPS و به‌روزرسانی Ubuntu

ابتدا با SSH وارد سرور شوید. دستورهای زیر روی خود VPS اجرا می‌شوند، نه روی کامپیوتر شخصی شما.

sudo apt update
sudo apt upgrade -y

سپس نسخه Ubuntu و معماری پردازنده را بررسی کنید:

cat /etc/os-release
dpkg --print-architecture

Docker به‌صورت رسمی از معماری‌های مختلف Ubuntu پشتیبانی می‌کند. در بیشتر VPSهای رایج خروجی معماری amd64 است.

مرحله ۲: نصب Docker Engine و Docker Compose

اگر Docker از قبل روی VPS نصب و سالم است، می‌توانید به مرحله بعد بروید. برای سرور خام، بهتر است Docker را از مخزن رسمی خود Docker نصب کنید.

مرحله ۲.۱ — نصب ابزارهای پایه و کلید رسمی Docker

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

مرحله ۲.۲ — اضافه‌کردن مخزن Docker

sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

مرحله ۲.۳ — نصب Docker و Compose Plugin

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

حالا وضعیت سرویس و نسخه Compose را بررسی کنید:

sudo systemctl status docker --no-pager
sudo docker compose version
sudo docker run --rm hello-world

اگر پیام موفقیت hello-world را دیدید، Docker Engine آماده است.

مرحله ۳: ساخت پوشه Stirling PDF

برای اینکه فایل‌های تنظیمات و داده‌های برنامه خارج از Container باقی بمانند، یک مسیر مشخص برای پروژه می‌سازیم:

sudo mkdir -p /opt/stirling-pdf
sudo chown -R "$USER":"$USER" /opt/stirling-pdf
cd /opt/stirling-pdf

mkdir -p stirling-data/tessdata
mkdir -p stirling-data/configs
mkdir -p stirling-data/logs
mkdir -p stirling-data/customFiles
mkdir -p stirling-data/pipeline

پوشه configs مهم است، چون تنظیمات و پایگاه داده محلی Stirling PDF در این بخش نگهداری می‌شود. با Mount کردن آن، حذف و ساخت مجدد Container باعث از بین رفتن تنظیمات برنامه نمی‌شود.

مرحله ۴: ساخت اطلاعات ورود اولیه

در Docker استاندارد Stirling PDF قابلیت Login وجود دارد. به‌جای اتکا به رمز پیش‌فرض، یک فایل .env می‌سازیم و اطلاعات اولیه مدیر را قبل از اولین اجرا تعیین می‌کنیم.

nano .env

محتوای زیر را وارد کنید و مقدار رمز را با یک رمز طولانی و تصادفی جایگزین کنید:

STIRLING_ADMIN_USER=pdfadmin
STIRLING_ADMIN_PASSWORD=CHANGE_THIS_TO_A_LONG_RANDOM_PASSWORD

در Nano با Ctrl+O فایل را ذخیره و با Ctrl+X خارج شوید. سپس دسترسی فایل را محدود کنید:

chmod 600 .env

مرحله ۵: ساخت docker-compose.yml

حالا فایل Compose را ایجاد کنید:

nano docker-compose.yml

این تنظیم برای یک نصب معمولی با Login، داده پایدار و Reverse Proxy مناسب است:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./stirling-data/tessdata:/usr/share/tessdata
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles:rw
      - ./stirling-data/pipeline:/pipeline
    environment:
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "${STIRLING_ADMIN_USER}"
      SECURITY_INITIALLOGIN_PASSWORD: "${STIRLING_ADMIN_PASSWORD}"
      SYSTEM_DEFAULTLOCALE: "en-US"
      SYSTEM_GOOGLEVISIBILITY: "false"
      SYSTEM_ROOTURIPATH: "/"
      SYSTEMFILEUPLOADLIMIT: "500MB"
    restart: unless-stopped

در این تنظیم، پورت 8080 فقط روی Loopback سرور قابل دسترسی است. در نتیجه کاربر اینترنت مستقیماً به Container وصل نمی‌شود و در مرحله بعد Nginx درخواست‌های HTTPS را به آن منتقل می‌کند.

مرحله ۶: اجرای Stirling PDF

ابتدا Image را دریافت و Container را اجرا کنید:

sudo docker compose pull
sudo docker compose up -d

وضعیت را بررسی کنید:

sudo docker compose ps
sudo docker compose logs --tail=100

اگر Container در وضعیت Up قرار دارد، از داخل خود VPS پاسخ برنامه را بررسی کنید:

curl -I http://127.0.0.1:8080

دریافت پاسخ HTTP نشان می‌دهد وب‌سرور برنامه اجرا شده است. اگر Connection Refused دریافت کردید، ابتدا خروجی docker compose ps و لاگ‌ها را بررسی کنید.

مرحله ۷: اتصال دامنه با Nginx

اگر می‌خواهید Stirling PDF را مثلاً روی pdf.example.com باز کنید، ابتدا در سرویس DNS دامنه یک رکورد A بسازید و آن را به IP سرور اشاره دهید. در تمام فرمان‌های این بخش، pdf.example.com را با دامنه واقعی خودتان جایگزین کنید.

Nginx را نصب کنید:

sudo apt install -y nginx

سپس فایل Virtual Host را بسازید:

sudo nano /etc/nginx/sites-available/stirling-pdf

تنظیم زیر را قرار دهید:

server {
    listen 80;
    server_name pdf.example.com;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

فایل را فعال و Syntax را بررسی کنید:

sudo ln -s /etc/nginx/sites-available/stirling-pdf /etc/nginx/sites-enabled/stirling-pdf
sudo nginx -t
sudo systemctl reload nginx

اگر nginx -t خطا داد، Nginx را Reload نکنید و ابتدا شماره خط و مسیر فایل اعلام‌شده در خطا را اصلاح کنید.

مرحله ۸: فعال‌سازی HTTPS

مستندات Production خود Stirling PDF توصیه می‌کنند دسترسی عملیاتی بدون HTTPS ارائه نشود، چون اطلاعات ورود و فایل‌های PDF در غیر این صورت روی مسیر شبکه رمزگذاری نمی‌شوند.

برای Nginx می‌توانید Certbot را نصب کنید:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d pdf.example.com

پس از پایان، آدرس زیر را در مرورگر باز کنید:

https://pdf.example.com

مرحله ۹: اولین ورود و بررسی امنیت

با نام کاربری و رمزی که در فایل .env تعیین کردید وارد شوید. اگر Stirling PDF را بدون تعیین Initial Login و با تنظیم پیش‌فرض بالا آورده باشید، مستندات حساب اولیه admin / stirling را اعلام می‌کنند و باید رمز آن را بلافاصله تغییر دهید.

مرحله ۱۰: تنظیم فایروال

اگر UFW روی سرور فعال است و Nginx را استفاده می‌کنید، SSH و پروفایل Nginx را مجاز کنید. قبل از تغییر فایروال مطمئن شوید Session فعلی SSH برقرار است تا دسترسی خودتان را قطع نکنید.

sudo ufw allow OpenSSH
sudo ufw allow "Nginx Full"
sudo ufw status

در Compose این آموزش، پورت 8080 فقط روی 127.0.0.1 منتشر شده است؛ بنابراین نیازی به ufw allow 8080 ندارید.

مرحله ۱۱: تست نهایی Stirling PDF

برای اینکه مطمئن شوید سرویس فقط «باز می‌شود» ولی واقعاً قابل استفاده هم هست، یک PDF آزمایشی غیرحساس بارگذاری کنید و یک عملیات ساده مثل Merge، Split یا Rotate انجام دهید.

برای مشاهده مصرف منابع در زمان پردازش فایل می‌توانید دستور زیر را اجرا کنید:

sudo docker stats stirling-pdf

چطور Stirling PDF را به‌روزرسانی کنیم؟

قبل از Update، از داده‌های پایدار نسخه پشتیبان بگیرید. برای این نصب، پوشه stirling-data شامل تنظیمات و داده‌های Persistent است.

cd /opt/stirling-pdf
mkdir -p backups
cp -a stirling-data "backups/stirling-data-$(date +%Y%m%d-%H%M%S)"

sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

بعد از Update، ورود، پردازش یک فایل آزمایشی و لاگ‌ها را دوباره بررسی کنید. برای محیط مهم سازمانی بهتر است قبل از حرکت به نسخه جدید، Release Notes و تغییرات نسخه را بخوانید.

خطاهای رایج نصب Stirling PDF روی VPS

Container مدام Restart می‌شود

اول لاگ و منابع سیستم را بررسی کنید:

sudo docker compose logs --tail=200
free -h
df -h

اگر حافظه سرور بسیار کم است، عملیات سنگین یا حتی راه‌اندازی بعضی قابلیت‌ها می‌تواند با مشکل مواجه شود. مستندات رسمی برای Production حداقل ۲ گیگابایت RAM و ۴ گیگابایت مقدار پیشنهادی را ذکر می‌کنند.

خطای Permission در Volumeها

ابتدا مالکیت و Permission پوشه‌های پروژه را بررسی کنید. صرف تنظیم 755 همیشه مشکل مالکیت را حل نمی‌کند.

ls -lah /opt/stirling-pdf
ls -lah /opt/stirling-pdf/stirling-data
sudo docker compose logs --tail=100

دامنه باز می‌شود اما آپلود فایل بزرگ خطا می‌دهد

محدودیت Upload در Reverse Proxy باید با محدودیتی که برای Stirling PDF تعیین کرده‌اید هماهنگ باشد. در نمونه این آموزش هر دو روی ۵۰۰ مگابایت تنظیم شده‌اند. Timeout پروکسی هم برای عملیات طولانی مهم است.

پورت 8080 قبلاً استفاده شده است

بررسی کنید چه پردازشی پورت را گرفته است:

sudo ss -lntp | grep :8080

اگر سرویس دیگری به 8080 نیاز دارد، می‌توانید سمت Host را مثلاً به 8081 تغییر دهید:

ports:
  - "127.0.0.1:8081:8080"

در این حالت مقدار proxy_pass در Nginx را هم به http://127.0.0.1:8081 تغییر دهید.

آیا Stirling PDF روی VPS ویندوز هم نصب می‌شود؟

بله. Stirling PDF نسخه Server مبتنی بر JAR برای Windows Server هم دارد. طبق مستندات فعلی، نسخه سرور JAR به Java JDK 25 نیاز دارد و برای قابلیت‌هایی مثل OCR یا برخی تبدیل‌ها ممکن است وابستگی‌های دیگری مثل Tesseract و LibreOffice لازم باشند.

با این حال، برای یک VPS لینوکسی که قرار است سرویس دائمی و قابل نگهداری باشد، Docker Compose مدیریت نصب، Volumeها و Update را ساده‌تر می‌کند؛ به همین دلیل مسیر اصلی این مقاله Ubuntu است.

سؤالات متداول

Stirling PDF چیست و چرا آن را روی VPS نصب کنیم؟

Stirling PDF یک مجموعه ابزار PDF قابل Self-Host است. با نصب آن روی VPS، یک رابط وب شخصی برای پردازش فایل‌های PDF در اختیار دارید و مدیریت سرور، دسترسی کاربران و تنظیمات سرویس در کنترل خودتان قرار می‌گیرد.

برای Stirling PDF حداقل چقدر RAM لازم است؟

راهنمای Production پروژه حداقل ۲ گیگابایت RAM و ۴ گیگابایت RAM را به‌عنوان مقدار پیشنهادی ذکر می‌کند. OCR، تبدیل فایل‌های بزرگ و کاربران هم‌زمان می‌توانند منابع بیشتری نیاز داشته باشند.

آیا بدون دامنه هم می‌توان Stirling PDF را اجرا کرد؟

بله، برنامه روی پورت 8080 اجرا می‌شود؛ اما برای دسترسی عمومی و دائمی بهتر است دامنه و HTTPS داشته باشید. در این آموزش پورت برنامه فقط روی localhost قرار گرفته و دسترسی بیرونی از طریق Nginx انجام می‌شود.

نام کاربری و رمز پیش‌فرض Stirling PDF چیست؟

در Docker استاندارد با Login فعال، مستندات حساب اولیه admin با رمز stirling را ذکر می‌کنند و کاربر در اولین ورود باید رمز را تغییر دهد. در این آموزش اطلاعات مدیر را قبل از اولین اجرا با متغیرهای Initial Login تعیین کردیم.

آیا فایل‌های PDF در حالت Self-Hosted به سرویس دیگری ارسال می‌شوند؟

عملیات Self-Hosted روی سروری که خودتان اجرا کرده‌اید انجام می‌شود، اما اگر در آینده قابلیت یا Provider خارجی مانند بعضی سرویس‌های AI را جداگانه فعال کنید، باید مسیر پردازش همان قابلیت را بررسی کنید. برای اسناد حساس، تنظیمات و سرویس‌های خارجی فعال را قبل از استفاده ارزیابی کنید.

چطور Stirling PDF را آپدیت کنیم؟

در نصب Docker Compose ابتدا از داده‌های Persistent بکاپ بگیرید، سپس docker compose pull و docker compose up -d را اجرا کنید. پس از Update، ورود، لاگ‌ها و یک عملیات PDF آزمایشی را بررسی کنید.

آیا Stirling PDF روی Windows Server هم اجرا می‌شود؟

بله. نسخه Server مبتنی بر JAR برای Windows Server ارائه می‌شود و در مستندات فعلی Java JDK 25 برای آن ذکر شده است. مسیر این مقاله روی Ubuntu و Docker متمرکز است.

منابع رسمی

🔹 راهنمای رسمی نصب Stirling PDF با Docker

🔹 راهنمای رسمی استقرار Production و HTTPS

🔹 مستندات Login و تنظیمات امنیتی Stirling PDF

🔹 Releaseهای رسمی Stirling PDF در GitHub

🔹 راهنمای رسمی نصب Docker Engine روی Ubuntu