Пошаговая инструкция · Самостоятельная установка
Как установить Paperless-ngx на сервер
Пошаговая инструкция для самостоятельной установки. Установим Paperless-ngx с PostgreSQL и распознаванием русского текста, настроим защищённый доступ, импорт документов, экспорт копии и восстановление.
Что подготовить и как читать инструкцию #
После установки получите архив по адресу docs.example.org: загруженные PDF и сканы распознаются, становятся доступны для поиска и сохраняются вместе с оригиналами. Здесь ставим один Paperless-ngx с PostgreSQL и Valkey. Обработка файлов Word/Excel через Tika и Gotenberg в основной сценарий не входит: её можно добавить после проверки PDF и изображений.
Возьмите Ubuntu 26.04 LTS с Docker Engine, Compose и Nginx, установленными по подготовке сервера. Создайте A-запись docs.example.org на публичный адрес. Уберите из DNS неработающий IPv6: получение сертификата иначе может завершиться ошибкой. Для доступа нужны TCP 80/443 и SSH; 8000 приложения будет открыт только на localhost, а PostgreSQL и Valkey останутся внутри Docker.
Команды выполняйте в терминале сервера после подключения по SSH, если шаг не указывает другое место. sudo даёт команде права администратора. Действия в браузере выполняйте на своём компьютере. Домены, IP-адреса и значения ВАШ_ПАРОЛЬ из примеров заменяйте своими до выполнения команды.
Двигайтесь по одному шагу и проверяйте результат перед следующим. Блок с <<EOF или другим именем завершения копируйте целиком: он записывает содержимое одного файла. При работе в nano сохраняйте файл клавишами Ctrl+O, Enter и выходите Ctrl+X. Если прервали SSH-сеанс, снова перейдите в указанный каталог; переменные предыдущего сеанса потребуется задать заново.
Настройка внешнего доступа использует обратный прокси Nginx и Certbot для Nginx. Приложение остаётся доступным на локальном порту; снаружи открыт его HTTPS-домен.
Шаг 1. Подготовьте каталог документов #
Создадим /opt/paperless и каталоги consume/export. Consume принимает новые файлы, export понадобится для переносимой копии.
sudo install -d -m 750 -o "$USER" -g "$USER" /opt/paperless
cd /opt/paperless
mkdir -p consume exportТекущий каталог — /opt/paperless.
Шаг 2. Создайте пароль PostgreSQL #
Пароль попадёт в .env с закрытыми правами. Он относится базе, а не администратору документов.
umask 077
printf 'COMPOSE_PROJECT_NAME=paperless\nPAPERLESS_DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .envФайл .env создан, PAPERLESS_DB_PASSWORD заполнен.
Шаг 3. Скачайте официальный Compose #
Берём вариант PostgreSQL из релиза v3.3.0. Не смешивайте его с Compose другой базы.
cd /opt/paperless
curl -fL -o docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/v3.3.0/docker/compose/docker-compose.postgres.ymlВ текущем каталоге появился docker-compose.yml.
Шаг 4. Подготовьте локальный порт и параметры базы #
Скрипт ниже изменяет только скачанный Compose: фиксирует выбранные версии, пароль и локальный адрес веб-интерфейса. База и очередь не должны публиковаться в Интернет.
python3 - <<'CONFIG'
from pathlib import Path
path = Path('docker-compose.yml')
text = path.read_text()
changes = {
'ghcr.io/paperless-ngx/paperless-ngx:latest': 'ghcr.io/paperless-ngx/paperless-ngx:3.3.0',
'"8000:8000"': '"127.0.0.1:8000:8000"',
'POSTGRES_PASSWORD: paperless': 'POSTGRES_PASSWORD: ${PAPERLESS_DB_PASSWORD:?}',
}
for old, new in changes.items():
assert text.count(old) == 1, old
text = text.replace(old, new)
path.write_text(text)
CONFIGВеб-порт 8000 привязан к 127.0.0.1; используется пароль из .env.
Шаг 5. Создайте ключ и узнайте UID пользователя #
Сгенерируйте ключ приложения. id выводит UID/GID пользователя, который владеет consume/export; они понадобятся в настройках.
openssl rand -hex 32
id -u
id -gСекрет сохранён, известны ваши UID и GID.
Шаг 6. Заполните docker-compose.env #
Откройте nano docker-compose.env и сохраните строки ниже. Замените домен, секрет и UID/GID своими. OCR распознаёт текст сканов; rus+eng включает русский и английский. Пароль базы подставляется из .env.
docker-compose.envPAPERLESS_URL=https://docs.example.org
PAPERLESS_SECRET_KEY=ЗАМЕНИТЕ_СЛУЧАЙНЫМ_КЛЮЧОМ
PAPERLESS_DBPASS=${PAPERLESS_DB_PASSWORD}
PAPERLESS_TIME_ZONE=Europe/Moscow
PAPERLESS_OCR_LANGUAGES=rus
PAPERLESS_OCR_LANGUAGE=rus+eng
USERMAP_UID=1000
USERMAP_GID=1000Нет ЗАМЕНИТЕ; домен ваш, UID/GID соответствуют владельцу папок.
Шаг 7. Проверьте параметры #
Закроем файл с настройками от постороннего чтения и проверим конфигурацию Compose.
cd /opt/paperless
chmod 600 docker-compose.env
docker compose config --quietconfig --quiet завершился без ошибки.
Шаг 8. Загрузите образы #
pull загружает приложение, базу и очередь. OCR-зависимости увеличивают размер загрузки; дождитесь завершения.
docker compose pullОбразы загружены успешно.
Шаг 9. Запустите Paperless #
Первый запуск создаёт структуру базы и готовит приложение.
docker compose up -dКонтейнеры созданы; далее проверим состояние.
Шаг 10. Дождитесь готовности #
Проверим контейнеры, журнал webserver и локальный ответ. Ошибки прав consume/export исправляйте сверкой UID/GID, а не выдачей прав 777.
docker compose ps
docker compose logs --tail=100 webserver
curl -I http://127.0.0.1:8000Webserver отвечает, база/очередь не перезапускаются.
Шаг 11. Сохраните сайт Nginx #
Установите Nginx и Certbot по подготовке Ubuntu, если ещё не установили. Откройте sudo nano /etc/nginx/sites-available/paperless-ngx и вставьте файл ниже. Замените все домены своими. Nginx передаёт приложению домен, адрес клиента и протокол; Upgrade и Connection сохраняют WebSocket. До получения сертификата условие $scheme блокирует обычные HTTP-запросы кодом 403, чтобы вход не происходил без шифрования. Лимит загрузки здесь 100 МБ; если нужен больший файл, измените client_max_body_size и сопоставьте с ограничением приложения.
/etc/nginx/sites-available/paperless-ngxmap $http_upgrade $paperless_ngx_connection_upgrade {
default upgrade;
"" close;
}
server {
listen 80;
server_name docs.example.org;
client_max_body_size 100m;
location / {
if ($scheme = http) { return 403; }
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $paperless_ngx_connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}
Сохраните Ctrl+O, Enter, Ctrl+X. В файле пока нет путей к сертификатам: Nginx сможет проверить его до выпуска HTTPS.
Шаг 12. Подключите сайт и проверьте HTTP #
Ссылка подключает сохранённый сайт. nginx -t проверяет все настройки сервера; && разрешает перечитать их только при успешной проверке. curl проверяет ответ для вашего домена. При ошибке остановитесь, исправьте указанную строку и повторите проверку.
sudo ln -sfn /etc/nginx/sites-available/paperless-ngx /etc/nginx/sites-enabled/paperless-ngx
sudo nginx -t && sudo systemctl reload nginx
curl -I http://docs.example.org/Ожидается successful от nginx -t и HTTP 403 для обычного запроса: до HTTPS это намеренная блокировка. DNS должен указывать на сервер, TCP 80/443 — быть доступен у провайдера. Ничего не вводите в форму входа по HTTP.
Шаг 13. Получите сертификат и включите HTTPS #
Каждое имя из команды должно указывать на этот сервер. Certbot проверит домены, сам добавит сертификат в сайт Nginx и включит перенаправление HTTP → HTTPS. Укажите свою почту при запросе и подтвердите условия Let’s Encrypt. Это отдельное действие после успешной проверки HTTP.
sudo /snap/bin/certbot --nginx -d docs.example.org --redirectCertbot сообщил об успешной установке. Откройте HTTPS-адрес со своего компьютера: браузер не должен предупреждать о сертификате. Для закрытой панели используйте разрешённый IP. При ошибке исправьте DNS, в том числе AAAA, либо доступ к TCP 80; не повторяйте запросы выпуска подряд.
Шаг 14. Проверьте продление сертификата #
Certbot из snap создаёт службу автоматического продления. Dry-run выполняет пробное продление: настоящие сертификаты не заменяются. Затем проверьте, что таймер планирует следующий запуск. Сохраняйте доступ к TCP 80 для следующих проверок домена.
sudo /snap/bin/certbot renew --dry-run
systemctl list-timers --all 'snap.certbot.renew*'Пробное продление успешно, у таймера есть следующий запуск. Если тест не прошёл, проверьте /var/log/letsencrypt/letsencrypt.log; сначала исправьте причину. После этого можно создавать учётную запись и приглашать пользователей.
Шаг 15. Создайте администратора #
Штатная createsuperuser интерактивно спросит логин, email и пароль. Это пользователь Paperless, не PostgreSQL.
docker compose exec webserver createsuperuserАдминистратор создан и входит в веб-интерфейс.
Шаг 16. Загрузите первый скан #
Подготовьте небольшой PDF с русским текстом без конфиденциальных данных. Загрузите через браузер и дождитесь завершения обработки. Очередь OCR может работать несколько минут.
Документ появился в списке; поиск находит слово из распознанного текста.
Шаг 17. Добавьте реквизиты и проверьте права #
Назначьте документу понятное имя, дату, корреспондента и тег. Создайте обычного пользователя и дайте доступ к тестовому документу.
Метаданные сохранились; обычный пользователь не видит документы без назначенного доступа.
Шаг 18. Создайте переносимый экспорт #
Document exporter сохраняет документы и данные в export. Дождитесь завершения перед архивацией. Это экспорт приложения, а не копирование работающего PostgreSQL по файлам.
cd /opt/paperless
docker compose exec -T webserver document_exporter ../exportВ export появились данные экспорта без ошибок.
Шаг 19. Сохраните экспорт и конфигурацию #
Подготовим закрытый каталог, архив экспорта и описание версий. Перенесите результат в закрытое хранилище вне сервера.
umask 077
PAPERLESS_BACKUP="$HOME/paperless-backup-$(date +%F-%H%M)"
mkdir -p "$PAPERLESS_BACKUP"
sudo tar -czpf "$PAPERLESS_BACKUP/export.tar.gz" export
cp .env docker-compose.env docker-compose.yml "$PAPERLESS_BACKUP/"
docker compose images > "$PAPERLESS_BACKUP/images.txt"Архив, оба env-файла, Compose и images.txt сохранены.
Шаг 20. Проверьте импорт на отдельном сервере #
Этот шаг выполняйте только на новом изолированном сервере с той же версией и пустой базой. Подготовьте установку предыдущими шагами и верните export из архива. Не импортируйте копию поверх действующей базы документов.
cd /opt/paperless
docker compose up -d db broker
docker compose run --rm webserver document_importer ../exportИмпорт завершился без ошибки; старый тестовый PDF появился в восстановленной системе.
Шаг 21. Запустите и проверьте восстановленную систему #
На тестовом сервере запустите весь комплект и проверьте целостность штатной командой. Затем найдите тестовый документ через браузер.
docker compose up -d
docker compose exec -T webserver document_sanity_checkerSanity checker не сообщает о потерянных файлах; документ открывается и находится поиском.
Если результат шага отличается #
Вернитесь к проверке того шага, на котором появилась ошибка. Первая ошибка в выводе обычно полезнее последних строк: последующие команды могли не получить нужный файл или работающую службу. Не повторяйте установку целиком поверх частично настроенного приложения.
Если страница не открывается, сначала проверьте домен и входящие порты, затем состояние приложения и его журнал. Если сайт открывается, но отдельное действие не работает, проверьте связанные компоненты — обработчик фоновых задач, почту или права пользователя. Официальные источники в конце статьи относятся к выбранному способу установки.
Настройки внешнего доступа храните вместе с копией приложения: /etc/nginx/sites-available/paperless-ngx и /etc/letsencrypt содержат сайт и сертификаты с закрытыми ключами. Архивируйте их с sudo в закрытое хранилище. После восстановления подключите сайт через sites-enabled, выполните sudo nginx -t, затем перечитайте Nginx. Для ошибки 502 сначала проверьте локальное приложение и /var/log/nginx/error.log; для сертификата — /var/log/letsencrypt/letsencrypt.log и таймер продления.