From fa6d1b64df7029cbac53f57f4bcedbf65c8c5dac Mon Sep 17 00:00:00 2001 From: Stiftung Development Date: Tue, 9 Sep 2025 22:00:32 +0200 Subject: [PATCH] Add Paperless-ngx to production deployment - Add Paperless-ngx service to Docker Compose configuration - Configure nginx routing for /paperless/ path with large file support - Add production environment variables for Paperless - Create automated setup script for initial Paperless configuration - Add comprehensive production setup documentation - Configure Paperless with HTTPS and proper database setup - Update Django app to use production Paperless instance --- deploy-production/docker-compose.prod.yml | 44 +++++++ deploy-production/nginx.conf | 16 +++ deploy-production/setup-paperless.sh | 63 ++++++++++ docs/paperless-production-setup.md | 142 ++++++++++++++++++++++ env-template.txt | 23 ++-- 5 files changed, 277 insertions(+), 11 deletions(-) create mode 100644 deploy-production/setup-paperless.sh create mode 100644 docs/paperless-production-setup.md diff --git a/deploy-production/docker-compose.prod.yml b/deploy-production/docker-compose.prod.yml index 95a6e45..0df1acb 100644 --- a/deploy-production/docker-compose.prod.yml +++ b/deploy-production/docker-compose.prod.yml @@ -141,6 +141,46 @@ services: memory: 512M cpus: '0.5' + paperless: + image: ghcr.io/paperless-ngx/paperless-ngx:latest + restart: unless-stopped + depends_on: + - db + - redis + ports: + - "127.0.0.1:8080:8000" + healthcheck: + test: ["CMD", "curl", "-fs", "-S", "--max-time", "2", "http://localhost:8000"] + interval: 30s + timeout: 10s + retries: 5 + volumes: + - paperless_data:/usr/src/paperless/data + - paperless_media:/usr/src/paperless/media + - paperless_export:/usr/src/paperless/export + - paperless_consume:/usr/src/paperless/consume + environment: + PAPERLESS_REDIS: redis://redis:6379 + PAPERLESS_DBHOST: db + PAPERLESS_DBNAME: ${PAPERLESS_DB:-paperless} + PAPERLESS_DBUSER: ${PAPERLESS_USER:-paperless} + PAPERLESS_DBPASS: ${PAPERLESS_PASSWORD:-paperless} + PAPERLESS_ADMIN_USER: ${PAPERLESS_ADMIN_USER:-admin} + PAPERLESS_ADMIN_PASSWORD: ${PAPERLESS_ADMIN_PASSWORD:-admin} + PAPERLESS_ADMIN_MAIL: ${PAPERLESS_ADMIN_MAIL:-admin@localhost} + PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY} + PAPERLESS_URL: https://vhtv-stiftung.de/paperless + PAPERLESS_ALLOWED_HOSTS: vhtv-stiftung.de,www.vhtv-stiftung.de + PAPERLESS_CORS_ALLOWED_HOSTS: https://vhtv-stiftung.de,https://www.vhtv-stiftung.de + PAPERLESS_TRUSTED_PROXIES: 172.16.0.0/12,10.0.0.0/8,192.168.0.0/16 + PAPERLESS_FORCE_SCRIPT_NAME: /paperless + PAPERLESS_STATIC_URL: /paperless/static/ + deploy: + resources: + limits: + memory: 2G + cpus: '1.0' + volumes: postgres_data: redis_data: @@ -149,6 +189,10 @@ volumes: gramps_thumb_cache: gramps_cache: gramps_secret: + paperless_data: + paperless_media: + paperless_export: + paperless_consume: networks: default: diff --git a/deploy-production/nginx.conf b/deploy-production/nginx.conf index a9240a8..15359f0 100644 --- a/deploy-production/nginx.conf +++ b/deploy-production/nginx.conf @@ -66,6 +66,22 @@ server { proxy_busy_buffers_size 256k; } + # Paperless-ngx document management + location /paperless/ { + 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_set_header X-Script-Name /paperless; + + # Large file uploads for documents + client_max_body_size 100M; + proxy_read_timeout 300s; + proxy_connect_timeout 300s; + proxy_send_timeout 300s; + } + # Gramps Web (optional) location /gramps/ { proxy_pass http://127.0.0.1:5000/; diff --git a/deploy-production/setup-paperless.sh b/deploy-production/setup-paperless.sh new file mode 100644 index 0000000..ecec773 --- /dev/null +++ b/deploy-production/setup-paperless.sh @@ -0,0 +1,63 @@ +#!/bin/bash + +# Paperless-ngx Production Setup Script +# Run this script after deploying the updated Docker Compose configuration + +set -e + +echo "πŸ”§ Setting up Paperless-ngx in production..." + +# Check if we're in the right directory +if [ ! -f "docker-compose.yml" ]; then + echo "❌ Error: docker-compose.yml not found. Please run this script from /opt/stiftung" + exit 1 +fi + +# Generate a random secret key for Paperless +echo "πŸ”‘ Generating Paperless secret key..." +PAPERLESS_SECRET=$(python3 -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())") + +echo "πŸ“ Add this to your .env file:" +echo "PAPERLESS_SECRET_KEY=$PAPERLESS_SECRET" +echo "" + +# Start containers +echo "πŸš€ Starting containers..." +docker-compose up -d + +# Wait for database to be ready +echo "⏳ Waiting for database to be ready..." +sleep 30 + +# Create database for Paperless if it doesn't exist +echo "πŸ—„οΈ Setting up Paperless database..." +docker-compose exec -T db psql -U ${POSTGRES_USER:-stiftung} -d ${POSTGRES_DB:-stiftung} -c "CREATE DATABASE paperless_prod;" || echo "Database may already exist" +docker-compose exec -T db psql -U ${POSTGRES_USER:-stiftung} -d ${POSTGRES_DB:-stiftung} -c "CREATE USER paperless_user WITH PASSWORD 'secure-paperless-password';" || echo "User may already exist" +docker-compose exec -T db psql -U ${POSTGRES_USER:-stiftung} -d ${POSTGRES_DB:-stiftung} -c "GRANT ALL PRIVILEGES ON DATABASE paperless_prod TO paperless_user;" || echo "Privileges may already be granted" + +# Run Paperless migrations +echo "πŸ“Š Running Paperless migrations..." +docker-compose exec -T paperless python3 manage.py migrate + +# Create Paperless superuser +echo "πŸ‘€ Creating Paperless superuser..." +echo "Note: You'll need to set a strong password for the admin user" +docker-compose exec paperless python3 manage.py createsuperuser --username admin --email admin@vhtv-stiftung.de + +# Get API token +echo "πŸ” Getting API token for Django integration..." +echo "You can get your API token by:" +echo "1. Visiting https://vhtv-stiftung.de/paperless/admin/" +echo "2. Going to Authentication and Authorization > Tokens" +echo "3. Creating a new token for your admin user" +echo "4. Adding the token to your .env file as PAPERLESS_API_TOKEN" + +echo "" +echo "βœ… Paperless-ngx setup complete!" +echo "" +echo "πŸ“š Next steps:" +echo "1. Update your .env file with the generated PAPERLESS_SECRET_KEY" +echo "2. Visit https://vhtv-stiftung.de/paperless/ to access Paperless" +echo "3. Create an API token in the Paperless admin interface" +echo "4. Update PAPERLESS_API_TOKEN in your .env file" +echo "5. Restart containers: docker-compose restart" diff --git a/docs/paperless-production-setup.md b/docs/paperless-production-setup.md new file mode 100644 index 0000000..f3bc15e --- /dev/null +++ b/docs/paperless-production-setup.md @@ -0,0 +1,142 @@ +# 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: + +```env +# 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: + +```bash +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: + +```bash +# 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 +```bash +docker-compose ps paperless +docker-compose logs paperless +``` + +### Database connection issues +```bash +docker-compose exec paperless python3 manage.py check --database default +``` + +### Nginx proxy issues +```bash +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/ diff --git a/env-template.txt b/env-template.txt index 987e4cd..f00bc72 100644 --- a/env-template.txt +++ b/env-template.txt @@ -14,23 +14,24 @@ DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1 # SECRET_KEY=your-production-secret-key-here # ALLOWED_HOSTS=your-domain.com,www.your-domain.com,localhost,127.0.0.1 -# HTTPS Security Settings (enable after SSL certificate is installed) -# SECURE_SSL_REDIRECT=True -# SESSION_COOKIE_SECURE=True -# CSRF_COOKIE_SECURE=True -# SECURE_HSTS_SECONDS=31536000 -# SECURE_HSTS_INCLUDE_SUBDOMAINS=True -# SECURE_HSTS_PRELOAD=True - LANGUAGE_CODE=de TIME_ZONE=Europe/Berlin # Redis Configuration REDIS_URL=redis://redis:6379/0 -# Paperless-ngx Integration -PAPERLESS_API_URL=http://192.168.178.167:30070 -PAPERLESS_API_TOKEN=e7107a43b6bef6707f11d7f7462708b87be3123c +# 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=generate-paperless-secret-key + +# Paperless-ngx Integration (for Django app) +PAPERLESS_API_URL=https://vhtv-stiftung.de/paperless +PAPERLESS_API_TOKEN=your-api-token-here # Tag-Namen (mit Unterstrichen, wie in Paperless NGX umbenannt) PAPERLESS_REQUIRED_TAG=Stiftung_DestinatΓ€re PAPERLESS_LAND_TAG=Stiftung_Land_und_PΓ€chter