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
-
Save the file as
docker-compose.yml. -
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:
- Install dependencies:
sudo apt update
sudo apt install -y python3 python3-venv python3-pip git libpq-dev
- 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
- 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!
