⚙️ Паровой сервер ROADIT
Войти Регистрация

Установка Paperless-ngx в Docker Compose на Ubuntu: Полное руководство для сисадмина

от

Протестировано на:

Ubuntu: 24.04

Бумага — это хорошо, но пар — лучше. В мире, где админу приходится хранить тысячи договоров, актов, счетов и служебных записок, бумажный архив становится настоящим паровым котлом, готовым взорваться в любой момент. Paperless-ngx — это ваш цифровой гнёздный манометр: система, которая превращает горы макулатуры в аккуратный, поисковый и полностью управляемый архив.

В этой статье мы с вами, коллеги, пройдём весь путь установки Paperless-ngx с помощью Docker Compose на Ubuntu. Без лишней романтики — только схемы, команды и рабочие конфиги.

Что такое Paperless-ngx и зачем он вам?

Paperless-ngx — это форк форка. Если по-простому: open-source система управления документами, которая умеет сканировать, распознавать (OCR) и индексировать ваши файлы. Вы просто скидываете PDF, JPEG или даже TIFF в специальную папку — система подхватывает документ, вытаскивает из него текст, раскладывает по тегам и делает полнотекстовый поиск.

Ключевые возможности:

  • Автоматический OCR — поддерживает PDF, изображения, Office-документы
  • Полнотекстовый поиск — ищет по содержимому, а не только по имени файла
  • Теги и соответствия — автоматическая классификация по правилам
  • Веб-интерфейс — современный, на Django + React
  • Почтовый импорт — забирает вложения из ящиков
  • REST API — для автоматизации и интеграций

Требования к железу: минимум 2 ядра CPU и 4 ГБ RAM. База данных — PostgreSQL (рекомендуется), Redis — для очередей.

Предварительная настройка котла: Docker и Docker Compose

Перед запуском нужно установить Docker и Docker Compose. Если у вас они уже есть — пропускайте. Если нет — настраиваем.

Установка Docker

sudo apt update
sudo apt install -y docker.io

Добавляем пользователя в группу docker:

sudo usermod -aG docker $USER
newgrp docker

Установка Docker Compose (два способа)

Пакет docker-compose-plugin может отсутствовать в стандартных репозиториях Ubuntu (ошибка E: Unable to locate package docker-compose-plugin). Ниже приведены два проверенных способа установки.

Способ А — через официальный репозиторий Docker (рекомендуемый)

Добавляем репозиторий и устанавливаем плагин:

# Устанавливаем зависимости
sudo apt-get install -y ca-certificates curl gnupg

# Добавляем GPG-ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий (подставьте свой коднейм, если $VERSION_CODENAME не работает)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновляем и устанавливаем плагин
sudo apt-get update
sudo apt-get install -y docker-compose-plugin

После этого команда docker compose (с пробелом) будет доступна.

Способ Б — установка бинарного файла (если нет доступа к репозиторию)

Скачиваем последнюю версию и делаем исполняемой:

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

В этом случае команда будет docker-compose (через дефис), все дальнейшие примеры можно использовать с этим синтаксисом.

Проверка установки

Выполните:

docker --version
docker compose version   # если ставили плагин
# или
docker-compose --version # если ставили бинарник

Требования: Docker не ниже 17.09.0, Compose не ниже 1.17.0.

Архитектура паровой машины: что мы разворачиваем

Типовой стек Paperless-ngx на Docker Compose включает три основных компонента:

КомпонентРоль
Web-серверОсновной контейнер с Django-приложением
WorkerФоновый обработчик задач (OCR, индексация)
RedisБрокер очередей для задач
PostgreSQLХранилище метаданных (рекомендуется)

Способ 1: Интерактивный установщик (для быстрого старта)

Самый простой способ — использовать официальный интерактивный скрипт. Он сам создаст docker-compose.yml, .env и запустит контейнеры.

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Скрипт задаст несколько вопросов:

  • URL (оставьте пустым для локального доступа)
  • Язык OCR — выберите rus для русского, eng для английского
  • UID/GID — оставьте по умолчанию
  • Пути к папкам — /consume, /media, /data
  • Учётные данные администратора — логин, пароль, email

После завершения откройте в браузере http://localhost:8000 и войдите под созданным пользователем.

Способ 2: Ручная настройка Docker Compose (для контроля над каждым винтиком)

Если вы предпочитаете держать руку на каждом клапане — собираем стек вручную.

Шаг 1. Создаём структуру каталогов

mkdir -p ~/paperless-ngx/{data,media,export,consume,pgdata}
cd ~/paperless-ngx

Где:

  • data — конфигурация и база SQLite (если не используете PostgreSQL)
  • media — загруженные документы
  • export — экспортированные архивы
  • consume — папка для автоматического импорта документов
  • pgdata — данные PostgreSQL (если используем)

Шаг 2. Создаём .env — файл переменных окружения

nano .env

Содержимое:

# Домен и URL
PAPERLESS_URL=http://localhost:8000
PAPERLESS_TIME_ZONE=Europe/Moscow

# Секретный ключ Django (обязательно сгенерируйте свой!)
PAPERLESS_SECRET_KEY=ваш_уникальный_ключ_минимум_32_символа

# Язык OCR
PAPERLESS_OCR_LANGUAGE=rus

# Пароль для базы данных
PAPERLESS_DBPASS=сильный_пароль

# Настройки PostgreSQL
POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=сильный_пароль

⚡ Важно

PAPERLESS_SECRET_KEY должен быть уникальным. Можно сгенерировать командой:

openssl rand -base64 48

Шаг 3. Создаём docker-compose.yml

nano docker-compose.yml

Пример конфига с PostgreSQL и Redis (адаптирован из официальных шаблонов):

services:
  postgres:
    image: postgres:16
    container_name: paperless-postgres
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    container_name: paperless-redis
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    container_name: paperless
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://redis:6379
      PAPERLESS_DBHOST: postgres
      PAPERLESS_DBNAME: ${POSTGRES_DB}
      PAPERLESS_DBUSER: ${POSTGRES_USER}
      PAPERLESS_DBPASS: ${PAPERLESS_DBPASS}
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_URL: ${PAPERLESS_URL}
      PAPERLESS_TIME_ZONE: ${PAPERLESS_TIME_ZONE}
      PAPERLESS_OCR_LANGUAGE: ${PAPERLESS_OCR_LANGUAGE}
    ports:
      - "8000:8000"

Запуск и проверка

Запускаем стек

docker compose up -d
# если используете бинарник: docker-compose up -d

Проверяем состояние:

docker compose ps
# или docker-compose ps

Смотрим логи:

docker compose logs -f paperless
# или docker-compose logs -f paperless

Создаём пользователя-администратора

Если использовали интерактивный скрипт — пользователь уже создан. Если ручной способ:

docker compose exec webserver python3 manage.py createsuperuser
# или docker-compose exec ...

Введите логин, email и пароль.

Первый документ — проверка работы

Самый простой способ проверить систему — положить PDF или изображение в папку consume:

cp ~/Документы/ваш_файл.pdf ~/paperless-ngx/consume/

Paperless-ngx автоматически подхватит файл, запустит OCR и добавит в архив. Через веб-интерфейс http://localhost:8000 вы увидите документ в списке.

Тонкая настройка: что ещё можно крутить

OCR Language

В .env можно указать несколько языков через запятую:

PAPERLESS_OCR_LANGUAGE=rus+eng

Работа с Office-документами (Tika)

Для поддержки DOCX, XLSX и PPTX нужен Apache Tika. Используйте Compose-файл с суффиксом -tika из официального репозитория.

Почтовый импорт

Настройте в веб-интерфейсе раздел Mail — Paperless сможет забирать вложения из вашего ящика по расписанию.

⚙️ Машинное отделение ROADIT благодарит за прочтение.
Больше команд, шпаргалок и обзоров — на roadit.ru и в нашем Телеграф-канале.
📋 Все команды

Оставьте комментарий