September 25, 2021 paperless-ng raspberry-pi self-hosted
Paperless-ng is an absolutely fantastic document archival solution that you can host yourself! What I like about this compared to the traditional folders method is that tags allow you to avoid duplicates. Furthermore, being able to search content and titles with OCR is absolutely amazing. However, just out of the box this paperless-ng isn’t that powerful as it (obviously) lacks connectivity. My preferred approach to this is via samba and email. As well as this, I use a external HDD to store all the data.
In this tutorial I will outline how I have set up my locally hosted paperless-ng instance with samba and email.
Note: Paperless-NG is now being maintained in a new fork. See this post for more information on upgrading.
Raspberry Pis run the OS from a SD card. Typical sizes of these cards are anywhere from 4gb to 64gb. However, if you’re serious about a scalable archiving, then a larger SD card will be required. 128gb cards are dead cheap these days at around £35, but nothing beats a good old 1tb external HDD. If you’re content with storing all your data on the SD card, then skip ahead to the next section. You can always come back and add extra storage so don’t worry about this step too much if all you’re wanting to do is get paperless-ng set up.
First thing you’ll need to do is find the path to your hard drive. This is
/dev/sda for me.
For reliable mounting, I like to use the UUID of the hard drive as the device path can change with mounts. This is found with
fdisk -l as outlined below. Your UUID will be different.
Next step is to create a mount point for the partition. Please excuse my hard drive naming convention…
Next, add the following to
fstab via your favourite editor (
sudo vim /etc/fstab). Important: change your UUID and mount locations as needed. I like formatting my portable drives using
exfat as this format is easily read on Windows machines too.
uid=1000 is the user id,
guid=1000 is the group id,
umask=022 this will set permissions so that the owner has read, write, execute. Group and Others will have read and execute.
To verify the config and to mount the hard drive, run
sudo mount -a.
Samba is a great solution for a locally hosted, networked instance of paperless-ng as it allows both windows, linux, and macOS devices to easily access the files. There are many many tutorials on how to use samba with your particular OS, such as via windows file explorer or by mounting the share using fstab, so I don’t feel the need to cover that. However, outlining how to setup samba on the RPi for paperless is unique.
Firstly install samba and the associated common binaries.
Then we create a folder somewhere on the filesystem. This tutorial uses a portable hard drive and thus we create a folder called
paperless on it. You can use any folder you desire though. Just make sure to change the steps as needed.
Add the following to the end of
Samba security works by allowing selected users access to partitions if
public=no. This means your
$USER is being added to the known list of users with access. For me this is
ubuntu as I’m using ubuntu server. The user is granted permission with
sudo smbpasswd -a $USER.
After all these changes have been made, restart
smbd on the RPi.
It’s always good practice to test that a service is properly configured after slaving away at the configs! For this particular case, the following gives us a quick overview:
Note that my RPis ip address is
192.168.0.73 and my samba user is
And that’s it! Samba is now set up for any verified user to use on your local network.
Actually setting up paperless-ng is incredibly simple thanks to
docker-compose (install it by following this great tutorial). Firstly we’ll download the config files for sqlite. Sqlite is lower power than postgres but obviously isn’t as powerful. If this instance of paperless-ng was being hosted on a more powerful machine, use postgres.
We download the previously mentioned
curl as below. Note we’re using the
arm flavour of the paperless-ng docker-compoes file as normal apache/tika does not support our architecture. For more info head to iwishiwasaneagle/apache-tika-arm.
I have then adjusted the file as follows:
9003as this suits my needs.
mediadocker volumes are changed to folders on my HDD to save space on the SD card.
./consumeare changed to the hard drive too for consistency. No data lives in these folders for long but I like having it all in one space.
env_filehas been deleted as I haven’t customised my setup.
Next pull the docker images with
docker-compose pull and create a paperless-ng superuser with:
Enter any username and password you’d like.
And finally to run your own instance of paperless-ng, run the following:
🚧 NOTE: The process for authenticating gmail accounts has changed. Have a look here for more information.
Paperless-ng makes it super simple to pull attachments from your emails. However, the IMAP method is simple and effective but I don’t like having my all-important gmail account’s password in a config file. Therefore I use a email account who’s sole use is being forwarded attachments.
For this step, you can use any email provider with IMAP support. I like using a throwaway gmail account that’s easy to remember. For the sake of this tutorial I’ll call it
[email protected] with password
G4kHXBurC7ngUt (both of these are random and any likeness to real emails or passwords are coincidence 😉 ).
Next you must complete the following two steps
Navigate to http://localhost:9003/admin/paperless_mail/mailaccount/. In this form you have to fill out the necessary IMAP information + a unique and identifiable name for this email.
This would be my setup for the aforementioned throwaway gmail account:
Once you’ve added an email account, you must add a rule to scrape your incoming emails. You can do this at http://localhost:9003/admin/paperless_mail/mailrule/
The following is the setup that works for me:
Paperless-ng is a truly amazing piece of FOSS software. Coupled with other common tools, like samba and email, it becomes a must have for anyone looking to archive documents.
Please show the paperless-ng some love here by staring the repo and if you have any comments, questions or queries about my setup, please use the comment section below!