flor1der/paperless-nextcloud-sync repository overview

⁠Paperless-ngx to Nextcloud Real-Time Synchronization via WebDAV

This Docker image mounts a remote WebDAV source and synchronizes the data from /mnt/source to the mounted WebDAV drive in real-time. It is designed for Nextcloud but also proven to work with other cloud systems:

✔ Nextcloud (tested version 30.0)
✔ ownCloud (tested version 10.15)
✔ OpenCloud (tested version 2.3)
✔ web.de smartdrive (tested in 2025-05)

⁠🧠 Why this Project?

This project provides a seamless way to connect Paperless and Nextcloud, overcoming limitations found in other solutions. It fulfills the following key requirements:

• Easy and quick configuration.
• Synchronization with remote Nextcloud instances.
• Files created, deleted, or modified appear in Nextcloud’s Activity Feed.
• PDFs can be fund using the search within Nextcloud.
• Real-time synchronization.

Click here to see a graphical overview of the container's functionality:

Here's a comparison between the data exchange options for Paperless and Nextcloud:

	Nextcloud Paperless App	Local Mount	SFTP or SMB/CIFS ¹	This Container
Easy SetUp	✅	✅	✅	✅ ²
Paperless Files available in Nextcloud	❌	✅	✅	✅
Send files to Paperless consume (File input)	✅ ³	☑️ ⁴	☑️ ⁴	❌ ³
Services on another Host (same Network)	✅	❌	✅	✅
remote Services	✅	❌	☑️ ⁵	✅
Files available in the Nextcloud Search	❌ ³	❌	❌	✅
Recent Paperless-changes available in Nextcloud Activity App	❌ ³	❌	❌	✅
Paperless Files backed up in Nextcloud ⁶	❌ ³	❌	❌	✅ ⁶
Works with both: Docker and Bare-Metal	✅	✅ ⁷	✅ ⁷	✖️ ⁸

¹ Additional FTP or SMB/CIFS service required
² see prerequisites
³ Nextcloud Paperless App: Nextcloud → Paperless / this container: Paperless → Nextcloud
⁴ a second external mount with writing permission required
⁵ only SFTP (SMB/CIFS not recommended over the Internet!)
⁶ this does NOT replace a regular backup including the Paperless Database
⁷ for Docker: ensure correct mounting
⁸ untested. Probably won't work OOTB and requires a more complex set-up

---

⁠📋 Preparation

You may configure the Paperless File name handling⁠ first.

⁠Requirements

• Administrative access to Nextcloud for adjusting user and brute-force settings.
• Dedicated Nextcloud account with read-write permissions for the synchronization container.

⁠Adjustments in Nextcloud

1. Create a Dedicated Account
   • Also create a dedicated folder for synchronization and sharing across your nextcloud.
   • Then share the folder as read-only with users/groups to maintain data consistency.
2. Brute-Force Settings
   • Set log level Info - to view throttled events in the log.
   • Add the container’s IP to the whitelist in Nextcloud to prevent throttling during initial synchronization.

---

⁠📥 Installation

⁠🛠️ Setup

1. Add the container to your Paperless stack using Docker Compose:

     nc-sync:
       image: flor1der/paperless-nextcloud-sync:latest
       volumes:
         - "/var/lib/docker/volumes/paperless_media/_data/documents/archive:/mnt/source:ro"
         - "./nc-sync_logs/:/var/log/"
       environment:
         WEBDRIVE_URL: $NEXTCLOUD_URL
         WEBDRIVE_USER: $NEXTCLOUD_USER
         WEBDRIVE_PASSWORD: $NEXTCLOUD_PASSWORD
         TZ: Europe/Berlin
       privileged: true
       devices:
         - "/dev/fuse"
   

   Copy

2. Replace my placeholders and define environment variables:

   • Under volumes: specify the mount-point of your document library

   • Fill in the WEBDRIVE_URL, WEBDRIVE_USER, and WEBDRIVE_PASSWORD values.

     • The WEBDRIVE_URL must be the WebDAV-URL of the folder.
       Example: https://www.DOMAIN.TLD/remote.php/dav/files/YOUR_USERNAME/FOLDERNAME
     • Use app passwords if two-factor authentication is enabled
       (User Settings > Security > Devices & sessions > Create new app password)
     • If you want to utilize Docker secrets⁠ use WEBDRIVE_PASSWORD_FILE instead of WEBDRIVE_PASSWORD.
     Click here to see the optional settings:

     • Define webdrive mount options using DIR_USER, DIR_GROUP, ACCESS_DIR, and ACCESS_FILE.
     • Set LC_ALL LANG and LANGUAGE to any value from this table⁠ if you experience filename issues with special characters.
     • Set the KEEP_LOGFILE_DAYS if the log files should be preserved for more/less than 90 days.
     • Look at the Advanced Functionalities⁠-section for custom cron capabilities.

3. Restart your Paperless instance to activate the container.

4. Verify the container is running:

   docker logs --follow <container-name>
   

   Copy

⁠🚀 Container Start

• The WebDAV drive will be mounted.
• The initial synchronization is started as background-job.
• A file watcher monitors changes in real-time.
• If WebDAV and file watcher is running: the container’s health status shows "healthy".
• Logs provide detailed information about the synchronization process.

⁠✔ Expected Results

• Initial synchronization uploads existing files, that are not existing in Nextcloud, newer in Paperless or moved/renamed.
• New files in Paperless are transferred to Nextcloud and appear in the Activity Feed:
  

---

⁠🧩 Advanced Functionalities

⁠Custom Cronjobs

This comes with some extra configuration you must set up, otherwise cronjobs will not work at all:

• copy the cronjob⁠-file from this repository to the stack/compose-directory on your docker host (e.g. as nc-sync_cronjobs)
• edit the file and run chown root and chmod 0644 on the file
  • Important: you need an empty line at the end of the file!
• mount as volume: - "./nc-sync_cronjobs:/etc/cron.d/cronjobs"

Do the same on scripts, if you like (but with chmod 0744)

⁠📌 Open Topics

• Replace initial synchronization with a better solution. My tests with rsync caused file deletions during synchronization, which my script avoids but still produces error messages (see log example⁠, lines 20-24). Please open issues only if you have a suitable solution!

---

⁠Like My Work?