starred/ProxmoxVE

Fork 0

mirror of https://github.com/community-scripts/ProxmoxVE.git synced 2026-04-25 17:26:03 +03:00

[PR #9223] [MERGED] Refactor: paperless-ngx (Breaking Change Inside) #7904

New issue

Closed

opened 2026-02-26 16:31:07 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 16:31:07 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/community-scripts/ProxmoxVE/pull/9223
Author: @MickLesk
Created: 11/17/2025
Status: ✅ Merged
Merged: 11/17/2025
Merged by: @michelroegl-brunner

Base: main ← Head: paperless_refactor

📝 Commits (2)

ba1a1d8 Refactor Paperless-ngx install and update scripts
115f1fb Update migration guide link in paperless-ngx.sh

📊 Changes

2 files changed (+46 additions, -62 deletions)

View changed files

📝 ct/paperless-ngx.sh (+24 -23)
📝 install/paperless-ngx-install.sh (+22 -39)

📄 Description

✍️ Description

Update scripts to use new data directory structure (/opt/paperless_data) and improve migration handling. Simplify backup logic to only include configuration files. Refactor database setup to use consistent environment variables and move cleanup to a dedicated function.

Migration Guide

Background

Previously, all data was stored in /opt/paperless/ alongside the application code. This caused several issues:

Updates overwrote user data: The update process would delete and reinstall the entire /opt/paperless directory
Filesystem inconsistencies: Users have different storage setups (ZFS, NFS mounts, LVM, tmpfs)
Python/Node.js conflicts: Mixed dependencies caused installation failures

The Solution

We now separate application code from user data:

Application: /opt/paperless/ (deleted and recreated on each update)
User Data: /opt/paperless_data/ (preserved across updates)

This is a one-time manual migration to ensure your data is in the correct location before updating.

Migration Steps

1. Create a Proxmox Snapshot (Highly Recommended!)

pct stop <CTID>
pct snapshot <CTID> pre-paperless-migration
pct start <CTID>

2. Stop Paperless-ngx Services

systemctl stop paperless-consumer paperless-webserver paperless-scheduler paperless-task-queue

3. Create New Data Directory

mkdir -p /opt/paperless_data/{consume,data,media,trash}

4. Move Your Data

# Move existing directories (only if they exist)
[[ -d /opt/paperless/consume ]] && mv /opt/paperless/consume/* /opt/paperless_data/consume/
[[ -d /opt/paperless/data ]] && mv /opt/paperless/data/* /opt/paperless_data/data/
[[ -d /opt/paperless/media ]] && mv /opt/paperless/media/* /opt/paperless_data/media/

5. Update Configuration

Edit /opt/paperless/paperless.conf and change the paths:

nano /opt/paperless/paperless.conf

Find and update these lines:

PAPERLESS_CONSUMPTION_DIR=/opt/paperless_data/consume
PAPERLESS_DATA_DIR=/opt/paperless_data/data
PAPERLESS_MEDIA_ROOT=/opt/paperless_data/media
PAPERLESS_EMPTY_TRASH_DIR=/opt/paperless_data/trash

6. Verify Your Data

# Check that all files were moved
ls -la /opt/paperless_data/consume/
ls -la /opt/paperless_data/data/
ls -la /opt/paperless_data/media/

7. Start Services and Test

systemctl start paperless-consumer paperless-webserver paperless-scheduler paperless-task-queue

Open Paperless-ngx in your browser and verify:

✅ All documents are visible
✅ Thumbnails load correctly
✅ Search works
✅ New document consumption works

8. Clean Up Old Directories (ONLY after verification!)

# Only delete these AFTER you've confirmed everything works!
rm -rf /opt/paperless/consume
rm -rf /opt/paperless/data
rm -rf /opt/paperless/media

9. Run the Update

Now you can safely run the update script after a new release is available:

update

Special Cases

NFS/CIFS Mounts

If you have network storage mounted:

Mount your storage to /opt/paperless_data/ instead
Update your /etc/fstab accordingly
Follow steps 3-9 above

Large Media Libraries

For large document collections, consider using rsync instead of mv:

apt install -y rsync
rsync -avh --progress /opt/paperless/media/ /opt/paperless_data/media/

Troubleshooting

Problem: Services won't start after migration

# Check logs
journalctl -u paperless-webserver -n 50
# and other services

Problem: Documents missing after migration

# Check if files were actually moved
find /opt/paperless -name "*.pdf"
# If found, move them to the new location

Problem: Database errors

# Restore from Proxmox snapshot
pct stop <CTID>
pct rollback <CTID> pre-paperless-migration
pct start <CTID>

✅ Prerequisites (X in brackets)

Self-review completed – Code follows project standards.
Tested thoroughly – Changes work as expected.
No security risks – No hardcoded secrets, unnecessary privilege escalations, or permission issues.

🛠️ Type of Change (X in brackets)

🐞 Bug fix – Resolves an issue without breaking functionality.
✨ New feature – Adds new, non-breaking functionality.
💥 Breaking change – Alters existing functionality in a way that may require updates.
🆕 New script – A fully functional and tested script or script set.
🌍 Website update – Changes to website-related JSON files or metadata.
🔧 Refactoring / Code Cleanup – Improves readability or maintainability without changing functionality.
📝 Documentation update – Changes to README, AppName.md, CONTRIBUTING.md, or other docs.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/community-scripts/ProxmoxVE/pull/9223 **Author:** [@MickLesk](https://github.com/MickLesk) **Created:** 11/17/2025 **Status:** ✅ Merged **Merged:** 11/17/2025 **Merged by:** [@michelroegl-brunner](https://github.com/michelroegl-brunner) **Base:** `main` ← **Head:** `paperless_refactor` --- ### 📝 Commits (2) - [`ba1a1d8`](https://github.com/community-scripts/ProxmoxVE/commit/ba1a1d8b3a5f35378117c8c589c21ed4f340a161) Refactor Paperless-ngx install and update scripts - [`115f1fb`](https://github.com/community-scripts/ProxmoxVE/commit/115f1fb7f06762287eec816fcf0c22d58d5866a7) Update migration guide link in paperless-ngx.sh ### 📊 Changes **2 files changed** (+46 additions, -62 deletions) <details> <summary>View changed files</summary> 📝 `ct/paperless-ngx.sh` (+24 -23) 📝 `install/paperless-ngx-install.sh` (+22 -39) </details> ### 📄 Description ## ✍️ Description Update scripts to use new data directory structure (/opt/paperless_data) and improve migration handling. Simplify backup logic to only include configuration files. Refactor database setup to use consistent environment variables and move cleanup to a dedicated function. # Migration Guide ### Background Previously, all data was stored in `/opt/paperless/` alongside the application code. This caused several issues: - **Updates overwrote user data**: The update process would delete and reinstall the entire `/opt/paperless` directory - **Filesystem inconsistencies**: Users have different storage setups (ZFS, NFS mounts, LVM, tmpfs) - **Python/Node.js conflicts**: Mixed dependencies caused installation failures ### The Solution We now separate application code from user data: - **Application**: `/opt/paperless/` (deleted and recreated on each update) - **User Data**: `/opt/paperless_data/` (preserved across updates) **This is a one-time manual migration** to ensure your data is in the correct location before updating. --- ## Migration Steps ### 1. Create a Proxmox Snapshot (Highly Recommended!) ```bash pct stop <CTID> pct snapshot <CTID> pre-paperless-migration pct start <CTID> ``` ### 2. Stop Paperless-ngx Services ```bash systemctl stop paperless-consumer paperless-webserver paperless-scheduler paperless-task-queue ``` ### 3. Create New Data Directory ```bash mkdir -p /opt/paperless_data/{consume,data,media,trash} ``` ### 4. Move Your Data ```bash # Move existing directories (only if they exist) [[ -d /opt/paperless/consume ]] && mv /opt/paperless/consume/* /opt/paperless_data/consume/ [[ -d /opt/paperless/data ]] && mv /opt/paperless/data/* /opt/paperless_data/data/ [[ -d /opt/paperless/media ]] && mv /opt/paperless/media/* /opt/paperless_data/media/ ``` ### 5. Update Configuration Edit `/opt/paperless/paperless.conf` and change the paths: ```bash nano /opt/paperless/paperless.conf ``` Find and update these lines: ```ini PAPERLESS_CONSUMPTION_DIR=/opt/paperless_data/consume PAPERLESS_DATA_DIR=/opt/paperless_data/data PAPERLESS_MEDIA_ROOT=/opt/paperless_data/media PAPERLESS_EMPTY_TRASH_DIR=/opt/paperless_data/trash ``` ### 6. Verify Your Data ```bash # Check that all files were moved ls -la /opt/paperless_data/consume/ ls -la /opt/paperless_data/data/ ls -la /opt/paperless_data/media/ ``` ### 7. Start Services and Test ```bash systemctl start paperless-consumer paperless-webserver paperless-scheduler paperless-task-queue ``` Open Paperless-ngx in your browser and verify: - ✅ All documents are visible - ✅ Thumbnails load correctly - ✅ Search works - ✅ New document consumption works ### 8. Clean Up Old Directories (ONLY after verification!) ```bash # Only delete these AFTER you've confirmed everything works! rm -rf /opt/paperless/consume rm -rf /opt/paperless/data rm -rf /opt/paperless/media ``` ### 9. Run the Update Now you can safely run the update script after a new release is available: ```bash update ``` --- ## Special Cases ### NFS/CIFS Mounts If you have network storage mounted: 1. Mount your storage to `/opt/paperless_data/` instead 2. Update your `/etc/fstab` accordingly 3. Follow steps 3-9 above ### Large Media Libraries For large document collections, consider using `rsync` instead of `mv`: ```bash apt install -y rsync rsync -avh --progress /opt/paperless/media/ /opt/paperless_data/media/ ``` --- ## Troubleshooting **Problem**: Services won't start after migration ```bash # Check logs journalctl -u paperless-webserver -n 50 # and other services ``` **Problem**: Documents missing after migration ```bash # Check if files were actually moved find /opt/paperless -name "*.pdf" # If found, move them to the new location ``` **Problem**: Database errors ```bash # Restore from Proxmox snapshot pct stop <CTID> pct rollback <CTID> pre-paperless-migration pct start <CTID> ``` ## ✅ Prerequisites (**X** in brackets) - [x] **Self-review completed** – Code follows project standards. - [x] **Tested thoroughly** – Changes work as expected. - [x] **No security risks** – No hardcoded secrets, unnecessary privilege escalations, or permission issues. --- ## 🛠️ Type of Change (**X** in brackets) - [ ] 🐞 **Bug fix** – Resolves an issue without breaking functionality. - [ ] ✨ **New feature** – Adds new, non-breaking functionality. - [x] 💥 **Breaking change** – Alters existing functionality in a way that may require updates. - [ ] 🆕 **New script** – A fully functional and tested script or script set. - [ ] 🌍 **Website update** – Changes to website-related JSON files or metadata. - [x] 🔧 **Refactoring / Code Cleanup** – Improves readability or maintainability without changing functionality. - [ ] 📝 **Documentation update** – Changes to `README`, `AppName.md`, `CONTRIBUTING.md`, or other docs. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem

2026-02-26 16:31:07 +03:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/ProxmoxVE#7904

No description provided.

Rows
Columns