Skip to content

Paperless-ngx — Runbook

Common Operations

Restart the stack

ssh [email protected]
cd /opt/paperless && docker compose restart

View logs

# All containers
cd /opt/paperless && docker compose logs -f

# Just paperless
docker logs -f paperless

# OCR processing
docker logs paperless 2>&1 | grep -i ocr

Or via Loki: {container="paperless"}

Check document count

docker exec paperless document_exporter --no-archive --no-original /dev/null 2>&1 | head -5

Or via API:

curl -s http://192.168.1.124:8000/api/documents/ \
  -H "Authorization: Token <api-token>" | jq '.count'

Trigger OCR reprocessing

docker exec paperless document_renamer

Export all documents

docker exec paperless document_exporter /usr/src/paperless/export
# Files land in /opt/paperless/export/

Import documents via consume folder

Drop files into /opt/paperless/consume/ on the LXC. Paperless picks them up automatically and processes them (OCR, classification, indexing).

# From any machine with SSH access:
scp document.pdf [email protected]:/opt/paperless/consume/

Database backup

docker exec paperless-postgres pg_dump -U paperless paperless > /opt/paperless/backup.sql

Database restore

docker exec -i paperless-postgres psql -U paperless paperless < /opt/paperless/backup.sql

Troubleshooting

Documents not being consumed

  1. Check consume directory has files: ls /opt/paperless/consume/
  2. Check paperless logs: docker logs paperless 2>&1 | tail -50
  3. Check file permissions: files need to be readable by UID 1000 inside the container

OCR producing bad results

  1. Check the language setting: PAPERLESS_OCR_LANGUAGE=eng
  2. Consider adding more language packs by extending the Docker image
  3. For difficult scans, consider using Paperless-GPT with a vision LLM — see AI Setup Guide

SSO login not working

  1. Verify PocketID is reachable: curl -s https://auth.eva-00.network/.well-known/openid-configuration
  2. Check callback URL matches PocketID client config
  3. Check Vault secrets match PocketID: POCKETID_CLIENT_ID, POCKETID_CLIENT_SECRET
  4. Check logs for OIDC errors: {container="paperless"} |= "social"

Search returning no results

  1. Check search index health: docker exec paperless document_index reindex
  2. Check PostgreSQL is running: docker exec paperless-postgres pg_isready
  3. Check disk space on heavy-pool: index lives on /opt/paperless/data/