Paperless-ngx Deployment Overview on Server¶

Prerequisites¶

The following system components and settings are required for the application to function correctly:

Operating System: Ubuntu.
System Dependencies: python3, python3-pip, python3-venv, python3-dev, redis-server, tesseract-ocr (including Russian language support tesseract-ocr-rus), imagemagick, ghostscript, unpaper, libpoppler-cpp-dev, libmagic-dev, mime-support, fonts-liberation.
Access Rights: Superuser privileges are required to install system packages and create users.

FQDN of the final panel on hostkey.in domain¶

Parameter	Value
Prefix	`paperless-ngx`
Domain	`hostkey.in`
Full Template	`paperless-ngx{Server_ID_from_Invapi}.hostkey.in`

File and Directory Structure¶

Main application and configuration directories:

/opt/paperless — Application root directory.
/opt/paperless/src — Application source code.
/opt/paperless/.venv — Python virtual environment.
/opt/paperless/data — Paperless database and working data.
/opt/paperless/media — Media files (documents) storage.
/opt/paperless/consume — Directory for uploading new documents for processing.
/opt/paperless/export — Data export directory.
/root/nginx — Nginx proxy server configurations and Docker Compose files.

Application Installation Process¶

Deployment is performed by extracting the v2.20.15 version archive from the GitHub repository into the /opt/paperless directory. After extraction, the following steps occur:

Creation of the paperless system user.
Installation of Python dependencies via pip into the virtual environment.
Execution of database migrations via manage.py migrate.
Creation of a superuser for web interface access.

Access Rights and Security¶

User: The paperless system user with home directory /opt/paperless is used to run the main processes.
ImageMagick Security: In the configuration file /etc/ImageMagick-6/policy.xml, PDF read and write permissions are enabled to ensure correct document processing.
Configuration: The paperless.conf file has 0640 permissions, accessible only by the paperless user and the paperless group.

Databases¶

An embedded database is used as storage (via Django ORM), while Redis running as a system service (redis-server) is used for task queue management and caching.

Docker Containers and Execution¶

To ensure web server operation with automatic SSL certificate acquisition, one container is used:

Image Name	Ports	Volumes	Environment Variables	Restart Policy
`jonasal/nginx-certbot:latest`	`443` (via host mode)	`nginx_secrets:/etc/letsencrypt`, `/data/nginx/user_conf.d:/etc/nginx/user_conf.d`	`[email protected]`	`unless-stopped`

Application Update Instructions¶

Updates are performed by updating packages or restarting the installation script. For the Nginx container, use the command:

docker compose up -d

in the /root/nginx directory.

Permissions Settings¶

All main working directories (data, media, consume, export) belong to the paperless user and the paperless group.

Configuration Files and Data Location¶

Paperless configuration: /opt/paperless/paperless.conf
Nginx configuration (Docker): /data/nginx/user_conf.d
SSL Secrets: in the nginx_secrets volume.

Available Connection Ports¶

Port	Purpose	Access Mode
`443`	HTTPS (via Nginx)	External access
`3000`	Paperless Web Interface	Internal (local)

Starting and Stopping the Application¶

Management of the main application components is performed via systemd:

Start all services:

systemctl start paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue redis-server

Stop services:

systemctl stop paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

Proxy Servers¶

Nginx in combination with Certbot is used to ensure a secure connection. The nginx-certbot container automatically manages the acquisition and renewal of Let's Encrypt SSL certificates. Traffic is redirected to the internal application port 3000.