Benoit Anastay Add-on: Paperless-ngx

FrankBurgenstein · June 11, 2025, 2:12pm

Benoit, this did the job

Fortunately my router is a FRITZ!Box and even more fortunately this Box offers a WireGuard connection. I connected my phone and now the paperless mobile app works fully well.
HA Companion also works better, only opening of documents gives an error “not supported” (so I think I still have some settings not accurate) but that is not important.

Thank you for helping me out. I am very grateful.

fishter · June 21, 2025, 10:15am

Hello,

I’ve reached a brick wall with mounting the consume and media folders as a network share.

I have a samba share which has one authorised user. This share is mounted in Home Assistant as “paperless”.

The paperless-ngx add on goes through the startup and changed the ownership of a bunch of files:

changed ownership of '/share/paperless/media/documents/originals/2014/xxx' from root:root to paperless:paperless
changed ownership of '/share/paperless/media/documents/originals/2014/xxx' from root:root to paperless:paperless
changed ownership of '/share/paperless/media/documents/originals/2014/xxx' from root:root to paperless:paperless
changed ownership of '/share/paperless/media/media.lock' from root:root to paperless:paperless
changed ownership of '/share/paperless/consume' from root:root to paperless:paperless
changed ownership of '/tmp/paperless' from root:root to paperless:paperless

Then I get this:

[init-checks] Running Django checks
SystemCheckError: System check identified some issues:
ERRORS:
?: PAPERLESS_CONSUMPTION_DIR is not writeable
HINT: Set the permissions of drwxr-xr-x root root /share/paperless/consume to be writeable by the user running the Paperless services
?: PAPERLESS_MEDIA_ROOT is not writeable
HINT: Set the permissions of drwxr-xr-x root root /share/paperless/media to be writeable by the user running the Paperless services

The only user on the samba server is the paperless user, which is uid/gid 1000. The network share is only accessible by this user (and is successfully mounted by HA as can be seen in the first log snippet above). The mounted share in HAOS is setup with this username/password.

On the samba end, all the folders and files are owned by paperless and have the group paperless. I can view, edit and delete files in the consume and media folders using the samba paperless username/password (same as is used for mounting the share in HA).

What is the missing connection between the paperless-ngx addon’s user and the samba user?
What am I missing in order to let the paperless-ngx add on have write access to the consume and media folders?
I’m totally flummoxed!

BenoitAnastay · June 21, 2025, 11:43am

You can set the UID:GID to 0:0 from the add-on settings tab

fishter · June 21, 2025, 12:14pm

Thank you!

I was setting the uid and gid to match the user on the samba server.

Now I can see the 500 docs I had already uploaded before running out of space - hence the network share config change.

BenoitAnastay · June 21, 2025, 1:23pm

You also need to enable polling interval for consume folder if it’s on a network share since inotify doesn’t work through samba

remmob · June 22, 2025, 2:44pm

I have the exact same issue, did you find a solution?

kulturschock · July 13, 2025, 5:56pm

Paperless NGX was not assigned the default hostname on my Home Assistant; Tika Gotenberg also has a modified hostname, which is why Paperless NGX cannot find Tika Gotenberg. Paperless ngx searches for hostname ca5234a0-tika-gotenberg, but it does not find it. Reinstalling did not help. The hostnames on my homeassistant are 55eca821-paperless-ngx and 55eca821-tika-gotenberg. I don’t know, how to change them. Can someone help me?

BenoitAnastay · July 14, 2025, 12:31am

I know this issue and a fix is planned but I have absolutly no time to work on it currently.

You can force the configuration by using the paperless.conf file

kulturschock · July 14, 2025, 9:44am

What should I change in the paperless.conf file?

BenoitAnastay · July 19, 2025, 12:15pm

The hostname of the tika addon.
You may need to uncheck tika addon from the paperless addon config tab

remmob · July 26, 2025, 6:02pm

The problem still exists today, and I’ve already run into a few more issues.
It seems that the paperless.conf is not read at all.

Merexor · July 29, 2025, 6:04am

Hi everyone, like some of you, I’d like to move my storage location to a Synology drive and access it with HomeAssistant/Paperless. I’ve already read a lot about adding network storage, etc., but does this really work or does it cause problems? Is there a defined way to do this correctly? Thanks in advance.

Merexor · July 31, 2025, 6:21am

I did it!
My way:

create a “Paperless” folder on the NAS and share it via NFS, for example (Google for information on the specific NAS so you can add the network storage to HA)
HA stop the Paperless add-on
HA FileEditor/Samba save the share folder as a backup, then rename it (e.g., Paperless_save)
HA add the network storage as a “paperless” share
HA copy the two folders “consume/media” from “paperless_save” to “paperless” in the share folder
HA once finished, delete paperless_save (a backup was saved in case of emergency )

After that, the add-on can be started.

When an error appears in the log during startup regarding permissions → stop the add-on and set the UID and GID to “0” in the config. The add-on should then start without problems.

As an additional option, you can have the respective scanner scan the consume folder, but you’d have to Google that anyway.
However, I would like to pass on two things:

correct permissions for the “consume” folder (Otherwise, the scanner cannot store anything)
Polling interval for the “consume” folder, in seconds! This interval is used to check for changes in this folder.

Have fun and I hope it works for you, too.
(Whoever finds these “instructions/guide”)

Statusbit · August 3, 2025, 9:04am

If I’d read your post earlier, it would have been easier

But I achieved exactly the same result yesterday using a similar method.

It’s important that the “paperless” network drive has the correct write permissions.

wrkn · August 13, 2025, 9:48pm

Yeah if you follow my thread, you just need to manually add all the permissions for your HA user that will be using ingress. (Sorry for delay, I only log in here when I am researching an issue)

remmob · August 20, 2025, 2:38pm

The Recusive consuming setting does not seem to work.
My external sysnology paperless consume directory only gets scant on restart add-on.
I also have tried to add the configuration to the config file. and also not seems to work.

BenoitAnastay · August 20, 2025, 9:17pm

You need to enable polling interval.

Files systems are using inotify but it’s not forwarded on network shares

KidSquid · September 9, 2025, 2:34pm

I must not be using the correct syntax for the share:

I have created a share called paperless as instructed.

In the paperless.conf file I have attempted to add the share path to the consumption and media paths…I have tried many ways…

share/paperless
//10.x.x.x/share/paperless
//10.x.x.x/paperless

PAPERLESS_CONSUMPTION_DIR=share/paperless
#PAPERLESS_CONSUMPTION_DIR=../consume
#PAPERLESS_DATA_DIR=../data
#PAPERLESS_EMPTY_TRASH_DIR=
PAPERLESS_MEDIA_ROOT=share/paperless

If I use just share/paperless a folder is created in HAOS called share with the paperless folder inside…

What the heck am I missing??

**ERRORS:**
**?: PAPERLESS_CONSUMPTION_DIR is set but doesn't exist.**
**HINT: Create a directory at /usr/src/paperless/src/10.x.x.x/paperless**

Can someone please help with the exact syntax for me to use to point to remote storage?

Many thanks…

Squid

BenoitAnastay · September 9, 2025, 6:33pm

You don’t need to edit the configuration, you just need to enable polling from the Home Assistant Addon Configuration tab

KidSquid · September 9, 2025, 6:46pm

@BenoitAnastay

I have tried that but I do not see folders created in the share.

Anything I can do to share additional debug information?