Deployment Overview of Paperless on Server¶

Prerequisites and Basic Requirements¶

The application requires a server running Ubuntu to function correctly. The following system requirements and dependencies must be met:

• Operating System: Ubuntu

• Privileges: Root or sudo access is required for installation.

• System Dependencies:

• Python 3 (including python3-pip, python3-venv, and python3-dev)

• Redis Server

• OCR and Image Processing: tesseract-ocr, tesseract-ocr-rus, imagemagick, ghostscript, unpaper

• PDF and File Utilities: libpoppler-cpp-dev, libmagic-dev, mime-support

• Fonts: fonts-liberation

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a specific subdomain template based on the server ID.

File and Directory Structure¶

The application utilizes several specific directories for data persistence and configuration:

• /opt/paperless: Main application directory.

• /opt/paperless/data: Application data storage.

• /opt/paperless/media: Media files storage.

• /opt/paperless/consume: Directory for incoming documents to be processed.

• /opt/paperless/export: Exported data directory.

• /root/nginx: Configuration and deployment files for the Nginx proxy.

• /data/nginx/user_conf.d: Custom Nginx user configurations.

Application installation process¶

The application is installed using a manual setup method involving source extraction and Python virtual environments:

1. System Setup: System dependencies are installed via apt, and Redis is enabled and started as a system service.

2. User Creation: A dedicated system user named paperless is created with the home directory /opt/paperless.

3. Source Retrieval: The Paperless-ngx version v2.20.15 is downloaded from GitHub, extracted to /opt/paperless, and configured for the paperless user.

4. Dependency Management: A Python virtual environment (.venv) is created within /opt/paperless. Specific database backends (like mysqlclient and psycopg-c) are removed from the requirements list before installing dependencies via pip.

5. Configuration: A paperless.conf file is generated to define application settings, including time zone (Europe/Moscow), OCR languages (rus+eng), and Redis connection strings.

6. Security Configuration: ImageMagick policy files are modified to allow the processing of PDF files.

7. Database Initialization: Database migrations are executed within the Python virtual environment.

8. Service Setup: Four systemd services are configured and enabled: paperless-webserver, paperless-consumer, paperless-scheduler, and paperless-task-queue.

Access Rights and Security¶

• User Isolation: The application runs under a dedicated paperless system user to minimize security risks.

• File Permissions: Configuration files like paperless.conf are restricted with mode 0640.

• Firewall/Proxy: An Nginx proxy handles external traffic, terminating SSL via Certbot.

Databases¶

The application uses Redis as a backend for task management and caching.

Docker Containers and Their Deployment¶

The deployment utilizes one primary container to manage SSL certificates and Nginx proxying.

Nginx Proxy Container

• Image: jonasal/nginx-certbot:latest

• Ports: 443 (External) / Host Network Mode

• Volumes:

• nginx_secrets:/etc/letsencrypt

• /data/nginx/user_conf.d:/etc/nginx/user_conf.d

• Environment Variables:

• [email protected]

• Restart Policy: unless-stopped

Custom Scripts and Additional Setup¶

The installation performs several automated setup actions:

• Superuser Creation: An administrative user (root) is automatically created within the application using a provided environment variable for the password.

• Environment Configuration: The paperless.conf file is dynamically populated with the correct FQDN based on the server's identity.

Application Update Instructions¶

To update the main Paperless-ngx application, follow these steps:

1. Download and extract the new version of the source code to /opt/paperless.

2. Re-run the Python dependency installation within the virtual environment:

   sudo -u paperless /opt/paperless/.venv/bin/pip install -r /opt/paperless/requirements.txt
   

3. Run database migrations:

   sudo -u paperless /opt/paperless/.venv/bin/python manage.py migrate
   

4. Restart the services to apply changes:

   sudo systemctl restart paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue
   

Location of configuration files and data¶

Available ports for connection¶

• HTTPS: 443 (via Nginx proxy)

• Internal Webserver: 3000 (local access only)

• Redis: 6379 (local access only)

Starting and Stopping the application¶

The application is managed via systemctl.

Starting all services:

sudo systemctl start paperless-webserver paperless-consumer paperless-scheduler paperless-task-queue

Stopping all services:

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