Complete Guide Installing Paperless-Ngx-with-Cloudpanel

Self-hosted Applications
,
1

Complete Guide: Installing Paperless-ngx with CloudPanel

Are you looking to go paperless and want to set up Paperless-ngx alongside your CloudPanel installation? This comprehensive guide will walk you through the entire process, from installation to troubleshooting common issues.

Prerequisites

Before we begin, ensure you have:

  • A server running Ubuntu 22.04/24.04 with SSH access
  • CloudPanel already installed and configured
  • Basic familiarity with command line operations
  • A domain or subdomain pointed to your server’s IP address

Part 1: Initial Setup

Step 1: Download and Prepare the Installation Script

First, let’s download our installation script:

mkdir -p /docker/scripts
cd /docker/scripts
wget https://git.hhf.technology/hhf/paperless_ngx_cloudpanel/raw/branch/main/paperless-install.sh
chmod +x paperless-install.sh

Step 2: Configure Installation Parameters

Before running the script, you might want to modify some default settings. Open the script in your preferred editor:

nano paperless-install.sh

Key parameters you might want to customize:

  • INSTALL_DIR: Default is “/docker/paperless-ngx”
  • PAPERLESS_TIME_ZONE: Set to your timezone
  • PAPERLESS_OCR_LANGUAGE: Default is “eng”

Step 3: Run the Installation Script

Execute the script with root privileges:

sudo ./paperless-install.sh

The script will:

  1. Check for and install Docker if needed
  2. Set up necessary directories
  3. Create and configure Docker containers
  4. Initialize the database
  5. Create a superuser account

Part 2: CloudPanel Configuration

Step 1: Create a New Site in CloudPanel

  1. Log into your CloudPanel dashboard
  2. Click “Sites” → “+ Add Site”
  3. Select “Reverse Proxy” as the site type
  4. Enter your domain (e.g., paperless.yourdomain.com)
  5. In the “Reverse Proxy URL” field, enter: http://localhost:8000
  6. Click “Create”

Step 2: Configure SSL Certificate

  1. Go to the SSL/TLS section of your new site
  2. Click “+ Create Let’s Encrypt Certificate”
  3. Follow the prompts to generate your certificate

Part 3: Common Issues and Troubleshooting

Issue 1: Docker Container Won’t Start

If you see errors about containers not starting:

# Check container logs
docker logs paperless-ngx-webserver-1

# Verify container status
docker ps -a

# Try restarting the container
docker compose restart webserver

Issue 2: Database Connection Issues

If you encounter database connection problems:

  1. Check if the database container is running:
docker ps | grep paperless-ngx-db
  1. Verify database credentials in docker-compose.yml:
cat /docker/paperless-ngx/docker-compose.yml | grep POSTGRES

Issue 3: OCR Not Working

If document OCR isn’t functioning:

  1. Check OCR language settings:
docker compose exec webserver ls /usr/share/tesseract-ocr/4.00/tessdata/
  1. Add additional languages by modifying docker-compose.yml:
environment:
  PAPERLESS_OCR_LANGUAGE: eng+fra+deu  # Add languages as needed

Issue 4: CloudPanel Proxy Error

If you get a 502 Bad Gateway error:

  1. Verify Paperless-ngx is running:
curl http://localhost:8000
  1. Check CloudPanel nginx logs:
tail -f /var/log/nginx/error.log

Issue 5: Memory Issues

If the system becomes slow or unresponsive:

  1. Check system resources:
docker stats
  1. Adjust container memory limits in docker-compose.yml:
services:
  webserver:
    deploy:
      resources:
        limits:
          memory: 2G

Part 4: Optimization and Best Practices

Regular Maintenance

Set up these maintenance tasks:

  1. Regular backups:
# Add to crontab
0 2 * * * /docker/paperless-ngx/export-backup.sh
  1. Log rotation:
# Configure logrotate
cat > /etc/logrotate.d/paperless-ngx <<EOF
/var/log/paperless-install.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}
EOF

Performance Tuning

For better performance:

  1. Configure Redis cache:
environment:
  PAPERLESS_TASK_WORKERS: 2
  PAPERLESS_THREADS_PER_WORKER: 2
  PAPERLESS_REDIS_URL: redis://broker:6379
  1. Optimize PostgreSQL:
services:
  db:
    command: postgres -c shared_buffers=256MB -c work_mem=16MB

Part 5: Updating Paperless-ngx

To update your installation:

cd /docker/paperless-ngx
docker compose pull
docker compose down
docker compose up -d

Conclusion

You now have a fully functional Paperless-ngx installation running behind CloudPanel! Remember to:

  • Regularly backup your data
  • Keep your system updated
  • Monitor system resources
  • Check logs periodically for any issues

For additional support:

Happy document managing!

2

The only thing holding me back on this project is, will my VPS handle it?
I have read that paperless-ngx processing is quite i/o intensive.

AMD EPYC 7282 2.8Ghz
4 vCPU Cores
8 GB RAM
400 GB SSD
32 TB Traffic Out / Traffic Incoming

The VPS only has docker for occasional experiments, and Cloudpanel.