Sep 4, 2024 3 min read

Paperless-ngx: Essential Tips for Successful Self-Hosting

Paperless-ngx: Essential Tips for Successful Self-Hosting
Table of Contents

Paperless-ngx is a powerful, self-hosted document management system designed for scanning, archiving, and organizing documents efficiently. It is an excellent choice for those who want full control over their data, as it offers robust features, customization options, and seamless integration with external tools. This guide will walk you through installing, configuring, and managing Paperless-ngx to help you unlock its full potential, from setup to advanced configurations.

Installing Paperless-ngx

πŸ“¦ Docker/Docker Compose Setup

Docker is the recommended way to deploy Paperless-ngx due to its ease of use and portability. Below is an example docker-compose.yml file tailored for Paperless-ngx:


version: "3.8"

services:

paperless-ngx:

image: ghcr.io/paperless-ngx/paperless-ngx:latest

container_name: paperless-ngx

restart: unless-stopped

environment:

PAPERLESS_SECRET_KEY: "your-secret-key"

PAPERLESS_TIME_ZONE: "UTC"

volumes:

- /path/to/data:/usr/src/paperless/data

- /path/to/media:/usr/src/paperless/media

ports:

- "8000:8000"

depends_on:

- db

db:

image: postgres:13

container_name: paperless-db

restart: unless-stopped

environment:

POSTGRES_USER: paperless

POSTGRES_PASSWORD: paperless

POSTGRES_DB: paperless

volumes:

- /path/to/db:/var/lib/postgresql/data

  1. Save the file as docker-compose.yml.

  2. Run the following commands to deploy Paperless-ngx:


mkdir -p /path/to/{data,media,db}

docker-compose up -d

This will spin up both the Paperless-ngx app and a PostgreSQL database.

πŸš€ Manual Installation

For those who prefer a manual setup, here’s how to install Paperless-ngx on a Linux server:

  1. Install dependencies:

sudo apt update

sudo apt install -y python3 python3-venv python3-pip git libpq-dev

  1. Clone the repository and set up the virtual environment:

git clone https://github.com/paperless-ngx/paperless-ngx.git

cd paperless-ngx

python3 -m venv venv

source venv/bin/activate

pip install -r requirements.txt

  1. Configure environment variables and start the app:

export PAPERLESS_SECRET_KEY="your-secret-key"

export PAPERLESS_TIME_ZONE="UTC"

./manage.py runserver 0.0.0.0:8000

Access Paperless-ngx at http://<your-server-ip>:8000.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To route traffic to Paperless-ngx, create an Nginx server block:


server {

listen 80;

server_name paperless.example.com;

location / {

proxy_pass http://127.0.0.1:8000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

}

Save this as /etc/nginx/sites-available/paperless, then enable it:


sudo ln -s /etc/nginx/sites-available/paperless /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your setup with Let's Encrypt:


sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d paperless.example.com

Automate certificate renewals:


sudo systemctl enable certbot.timer

πŸ› οΈ Testing and Reloading Nginx

Ensure your Nginx configuration is correct:


sudo nginx -t

sudo systemctl reload nginx

Logging and Debugging Paperless-ngx

πŸ—ƒοΈ Enabling Debug Logs

Enable debug logs by setting PAPERLESS_LOG_LEVEL in your environment:


export PAPERLESS_LOG_LEVEL=DEBUG

πŸ“„ Viewing Logs

For Docker-based setups, view logs with:


docker logs paperless-ngx

For manual setups, check the logs in the application directory:


tail -f logs/paperless.log

πŸ› οΈ Troubleshooting Common Issues

If Paperless-ngx fails to start, check database connectivity or missing environment variables:


docker exec -it paperless-ngx bash

python manage.py check

πŸ“€ Exporting Logs

To send logs to an external system, configure your Docker logging driver or use tools like Fluentd.

Backup and Restore

πŸ—‚οΈ File-Based Backups

To back up your volumes:


tar -czf paperless-backup.tar.gz /path/to/data /path/to/media /path/to/db

πŸ”„ Database Backups

Export your PostgreSQL database:


docker exec -it paperless-db pg_dump -U paperless -d paperless > paperless-db-backup.sql

Restore the database:


docker exec -i paperless-db psql -U paperless -d paperless < paperless-db-backup.sql

πŸ“… Automated Backup Scripts

Create a daily backup using cron:


echo "0 2 * * * tar -czf /backup-dir/paperless-$(date +\%F).tar.gz /path/to/data /path/to/media /path/to/db" | crontab -

Updating and Upgrading Paperless-ngx

⬆️ Updating Docker Images

Update to the latest Paperless-ngx version with:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations:


cd /path/to/paperless-ngx

git pull

source venv/bin/activate

pip install -r requirements.txt

Restart the server:


./manage.py runserver

πŸ” Checking for Updates

Monitor Paperless-ngx’s GitHub repository for new releases:


git remote update

git status

Leveraging Paperless-ngx’s Unique Features

πŸ”§ Enabling APIs

To enable and test the API, first set PAPERLESS_API in your environment:


export PAPERLESS_API=true

Test the API with curl:


curl -X GET http://127.0.0.1:8000/api/documents/ -H "Authorization: Token <your-token>"

🌟 Advanced Configurations

Integrate tools like OCR for better indexing:


sudo apt install tesseract-ocr

export PAPERLESS_OCR_LANGUAGES="eng+deu"

Wrapping Up

This guide has covered everything from installing Paperless-ngx to configuring Nginx, managing logs, and leveraging its unique features. By self-hosting Paperless-ngx, you gain complete control over your document management system, ensuring security and customization tailored to your needs. Start implementing the provided examples today to take full advantage of this flexible and powerful tool!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.