stiftung-management-system/docs/paperless-production-setup.md

Paperless-ngx Production Setup

This document explains how to set up Paperless-ngx on your production server alongside your Django application.

Overview

Paperless-ngx will be deployed as part of your Docker Compose stack and accessible at:

• URL: https://vhtv-stiftung.de/paperless/
• Admin: https://vhtv-stiftung.de/paperless/admin/

Prerequisites

• Your Django application is already deployed and working
• HTTPS is configured and working
• You have SSH access to your production server

Setup Steps

1. Deploy the Updated Configuration

The Docker Compose configuration already includes Paperless-ngx. After pushing the latest changes, it will be deployed automatically.

2. Configure Environment Variables

Add these variables to your production .env file:

# Paperless-ngx Production Configuration
PAPERLESS_DB=paperless_prod
PAPERLESS_USER=paperless_user
PAPERLESS_PASSWORD=secure-paperless-password
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=secure-admin-password
PAPERLESS_ADMIN_MAIL=admin@vhtv-stiftung.de
PAPERLESS_SECRET_KEY=your-generated-secret-key

# Paperless-ngx Integration (for Django app)
PAPERLESS_API_URL=https://vhtv-stiftung.de/paperless
PAPERLESS_API_TOKEN=your-api-token-here

3. Run the Setup Script

On your production server:

cd /opt/stiftung
chmod +x deploy-production/setup-paperless.sh
./deploy-production/setup-paperless.sh

4. Update Django Configuration

Your Django app will automatically use the new Paperless instance once you:

1. Update the PAPERLESS_API_URL in your .env file
2. Get an API token from Paperless admin interface
3. Update the PAPERLESS_API_TOKEN in your .env file
4. Restart the containers

Security Features

• ✅ HTTPS encryption for all Paperless traffic
• ✅ Nginx reverse proxy with security headers
• ✅ Separate database for Paperless data
• ✅ Docker container isolation
• ✅ Large file upload support (100MB)

File Management

Paperless will store files in Docker volumes:

• Data: paperless_data - Database and configuration
• Media: paperless_media - Processed documents
• Export: paperless_export - Export files
• Consume: paperless_consume - Documents to be processed

Backup Strategy

Paperless data is stored in Docker volumes. To backup:

# Backup Paperless volumes
docker run --rm -v paperless_data:/data -v $(pwd):/backup alpine tar czf /backup/paperless_data_backup.tar.gz -C /data .
docker run --rm -v paperless_media:/data -v $(pwd):/backup alpine tar czf /backup/paperless_media_backup.tar.gz -C /data .

Migration from Local Installation

To migrate your existing Paperless data:

1. Export from local Paperless: Use the export function in your local admin interface
2. Import to production: Use the import function in the production admin interface
3. Update tags and settings: Reconfigure any custom tags or workflows

Troubleshooting

Check container status

docker-compose ps paperless
docker-compose logs paperless

Database connection issues

docker-compose exec paperless python3 manage.py check --database default

Nginx proxy issues

sudo nginx -t
sudo tail -f /var/log/nginx/error.log

API Integration

Once setup is complete, your Django application will automatically connect to the production Paperless instance using the configured API token.

The integration includes:

• Document searching and filtering
• Tag management
• User access control
• File upload and processing

Performance Considerations

• Paperless is allocated 2GB RAM and 1 CPU core
• Large document processing may take time
• Consider increasing resources if needed
• Monitor disk usage for document storage

Next Steps

After successful setup:

1. Configure document consumption workflows
2. Set up document tags and correspondents
3. Import existing documents
4. Test Django app integration
5. Set up automated backups

For support, check the Paperless-ngx documentation at: https://paperless-ngx.readthedocs.io/