Deploying Paperless-ngx Document Management

Managing paperless effectively is a crucial skill for any system administrator. This tutorial provides step-by-step instructions for documents configuration, along with best practices for production environments.

Prerequisites

• Docker and Docker Compose installed
• A reverse proxy configured (Nginx or Traefik)
• A registered domain name (for public-facing services)
• Basic familiarity with the Linux command line
• Root or sudo access to the server

Docker Compose Setup

Before making changes to the configuration, always create a backup of the existing files. This ensures you can quickly roll back if something goes wrong during the setup process.

# docker-compose.yml
version: '3.8'
services:
  paperless:
    image: paperless/paperless:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - paperless_data:/data
      - paperless_config:/config
    environment:
      - TZ=UTC
      - PUID=1000
      - PGID=1000
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=paperless
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD=changeme

volumes:
  paperless_data:
  paperless_config:
  db_data:

Each line in the configuration serves a specific purpose. The comments explain the reasoning behind each setting, making it easier to customize for your specific use case.

• Profile before optimizing - measure first
• Start with the minimum required resources
• Use connection pooling for database connections
• Implement caching at every appropriate layer

Initial Configuration

Performance benchmarks show that properly tuned paperless can handle significantly more concurrent connections than the default configuration. The key improvements come from adjusting worker processes and connection pooling.

# Reverse proxy configuration
server {
    listen 443 ssl http2;
    server_name paperless.example.com;

    ssl_certificate /etc/letsencrypt/live/paperless.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/paperless.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        client_max_body_size 0;
    }
}

This configuration provides a good balance between performance and resource usage. For high-traffic scenarios, you may need to increase the limits further.

• Use SSH keys instead of password authentication
• Use strong, unique passwords for all services
• Keep all software components up to date

Reverse Proxy Integration

If you encounter issues during setup, check the system logs first. Most problems can be diagnosed by examining the output of journalctl or the application-specific log files in /var/log/.

# docker-compose.yml
version: '3.8'
services:
  paperless:
    image: paperless/paperless:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - paperless_data:/data
      - paperless_config:/config
    environment:
      - TZ=UTC
      - PUID=1000
      - PGID=1000
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=paperless
      - POSTGRES_USER=paperless
      - POSTGRES_PASSWORD=changeme

volumes:
  paperless_data:
  paperless_config:
  db_data:

Note that file paths may vary depending on your Linux distribution. The examples here are for Debian/Ubuntu; adjust paths accordingly for RHEL/CentOS-based systems.

• Monitor disk space usage and set up alerts
• Review log files weekly for anomalies
• Enable automatic security updates for critical patches
• Keep your system packages updated regularly
• Test your backup restore procedure monthly

Common Issues and Solutions

• Service won't start: Check the logs with journalctl -xe -u paperless. Common causes include port conflicts, missing configuration files, or insufficient permissions.
• Permission denied errors: Ensure files and directories have the correct ownership. Use chown -R to fix ownership and chmod for permissions.

Conclusion

This guide covered the essential steps for working with paperless on a VPS environment. For more advanced configurations, refer to the official documentation. Don't hesitate to reach out to our support team if you need help with your specific setup.