In this tutorial, we will be showing you how to install and run Paperless-NG on the Raspberry Pi.
Paperless-NG is a powerful software designed to act as a digital archive/index for all your paper documents.
When you feed Paperless-NG a document. it will perform OCR (Optical Character Recognition) over it, turning images into searchable and selectable text.
This is just scraping the surface of what Paperless is capable of. You should definitely check out this software if you need a central place to aggregate your documents.
The Raspberry Pi is an excellent device for Paperless-NG as it uses a low amount of power, making it cheap to run continually.
For the best experience with Paperless-NG, you should use a Raspberry Pi 4 or newer with 4GB of memory or more. Additionally, it would help if you also were using a 64-bit operating system so that it can make the most of your device’s memory.
Equipment
Below is a list of the equipment we used when setting up Paperless-NG on our Raspberry Pi.
Recommended
Optional
This tutorial was tested on a Raspberry Pi 400 running the latest release of Raspberry Pi OS Bullseye 64-bit.
Preparing your Raspberry Pi for Paperless-NG
This section will show you the steps of preparing your Raspberry Pi for Paperless-NG.
The main two tasks we need to do here are to install “docker-compose” and create a directory where Paperless will ingest documents.
1. Before we do anything, we will need to update the package list and upgrade any out-of-date packages.
To achieve these tasks, run the following two commands in the terminal.
2. Once the update completes, we can install the packages we need to run Paperless-NG. Thanks to Paperless coming in a docker container, we only need to install Docker.
You can install “docker-compose” to your Raspberry Pi using the following command.
3. Now that we have installed Docker, we need to make a directory from which Paperless will retrieve any new documents.
For this tutorial, we will create a folder within the user’s home directory called “consume” that will sit within another directory called “paperless“.
You can create these directories by using the command below in the terminal.
Installing Paperless-NG on the Raspberry Pi
With our Raspberry Pi prepared, we can move on to installing Paperless-NG. In these steps, we will write a “docker-compose.yml” file and an environment file needed to install and run Paperless-NG.
1. Let us start by moving into the directory that we created in an earlier step.
You can change to this directory using the cd command within the terminal.
Creating the docker-compose.yml File
2. Once we are in the “paperless” directory, we can begin writing this Docker configuration file using the following command.
This file tells Docker what containers it needs to download and run.
3. Within this config file, type in the following lines. We will explore a couple of the options you might want to adjust in a bit.
4. Within the configuration file, there is a couple of things you might want to adjust for Paperless-NG to fit your Raspberry Pi.
If you are happy to stick with the default settings, you can skip to the next step.
Changing the Port Paperless-NG Operates On
The first thing you might want to change is the port Paperless-NG is utilizing on your Raspberry Pi.
By default, it will operate on port 8000 but it is possible to change this to another port.
To change the port, you will want to replace the number on the left side of the colon.
For example, if you wanted to change it so that Paperless runs on port 8080, you would change it to look like the below.
Changing the Ingest Directory
The other option you might want to change is the location wnere Paperless will look for files on your Raspberry Pi. By default, this will be the relative directory with the name “consume” (We created a place for this earlier in the tutorial).
If you want to change the directory that Paperless imports documents from, you will want to change the directory on the left side of the column.
For example, if you wanted to import folders from a share mounted at “/mnt/paperless“, you would change this line to look like the following.
5. Once you have finished editing this file, you can save and quit by pressing CTRL + X, followed by Y, then ENTER.
Writing the Paperless-NG Environment File
6. We will need a random string to use as the secret key for Paperless-NG.
You can generate a random key by using the following command in the terminal.
After running this command, you should get a result like the one below. Copy this string, as we will use it within the next step.
7. We can begin writing the “docker-compose.env” file by running the following command.
8. Within this file, you will need to write the following lines. We will explain each piece as we insert them.
The first line we will add sets the secret key for Paperless. Replace “YOURSECRETKEY” with the key you generated in step 6.
9. Let us start with the “USERMAP” options. These options map the Docker container to a specific user and group. With Raspberry Pi OS the main user will have an ID of 1000.
You will need to change these values if you are using a different
10. The next option allows you to add additional languages for Paperless to support on your Raspberry Pi. If the default languages are all you need, you can skip adding this option.
By default, Paperless supports the English, German, Italian, Spanish and French languages. However, the software can support numerous more by looking at the Debian package list.
Each additional language should be referenced by its three-letter code (E.G ces for Czech). You can add multiple additional languages by separating each one by a single space
11. By default Paperless-NG will use the UTC time zone. However, we can change this to your local time zone by setting the “PAPERLESS_TIME_ZONE” option.
You can find a list of time zones on Wikipedia. The value you are after is in the “TZ database name” column.
For example, we would use the following line to set the time zone to Hobart, Australia.
12. The final option we will explore in this section is to set the default language Paperless will use on your Raspberry Pi for OCR.
You should set this option to the language that most of your documents will be in.
With the line we are adding below, we will set the default language to English.
13. Once done, you can save and quit by pressing CTRL + X, followed by Y, then the ENTER key.
Running Paperless-NG Installation on the Raspberry Pi
14. Finally, we can run Paperless on the Raspberry Pi by using the following command.
Docker will immediately begin downloading all required containers and start them up using our configuration.
Depending on your internet connection speed, this process can take some time.
Creating a User for Paperless-NG’s Web Interface
15. Once Paperless-NG is up and running on your Raspberry Pi you will need to create a user.
To start this process, you must run the following command within the terminal.
16. The first thing you will be asked is to specify a username for your new user.
If you press ENTER without typing anything, Paperless will create the user with the name “paperless“.
18. You will now be asked to enter an email address for this user optionally.
You can leave this space if you don’t want to assign the user an email.
19. Next, you will be required to type in the password for this user. Ensure this is something secure and doesn’t too closely match your email address or username.
You will be required to re-enter the password to confirm it.
20. If your user for Paperless-NG has been successfully created, you should see the following message in the terminal.
You can now move on to logging in and using Paperless on your Raspberry Pi.
Using the Raspberry Pi’s Paperless-NG Web Interface
Over the next few sections we will be showing you how to access and use Paperless-NG’s web interface.
All you need for this section is your favourite web browser and a connection to your Raspberry Pi.
Accessing the Paperless-NG Web Interface
1. To access the Paperless-NG web interface on your Raspberry Pi, you need to know its IP address.
The easiest way to grab the IP of your Raspberry Pi is to use the hostname command in the terminal.
Typically, the IP assigned to your Pi will be the first address listed.
2. Once you know the IP address of your Raspberry Pi you will want to go to the following address.
Ensure you replace “IPADDRESS” with your IP. You would also need to change port “8000” if you changed the port within the Docker config file.
3. You will now be greeted by the Paperless login screen. On this screen, you will need to fill out both the username and password (1.) you set in the previous section.
With your login details filled out, click the “Sign in” button (2.).
4. You will now be greeted by the Paperless-NG dashboard. You can use this dashboard to view all of your documents and manage them.
It is possible to even use this interface to manually upload your documents to Paperless to process.
Uploading a Document to Paperless through the Web Interface
5. To upload a file to your Raspberry Pi through Paperless you will want to drag and drop it on the left-sidebar as shown.
Alternatively, you can click the “Browse files” button and manually select the documents you want to upload.
6. Upon uploading a file to Paperless, it will automatically begin processing the document.
This process can take time as it needs to scan the entire document.
Editing a Processed Document
7. Once you have documents uploaded to Paperless, it is possible to edit the metadata generated for it. This is useful for properly categorizing all the different documents you upload.
Editing the metadata will also help Paperless’s machine learning automatically categorize your documents.
To edit a document, you can click “Open document” (1.) immediately after uploading it.
Alternatively, you can find these documents on the “Documents” page (2.)
8. Below, you can see the edit screen for a screenshot that we uploaded to Paperless.
It has attempted to scan through the document allowing you to easily highlight and copy text.
You can use the documents screen to edit various details about this document such as the title, tags, document type, and more.
Conclusion
At this point, you should now have Paperless-NG up and running on your Raspberry Pi.
Paperless is a powerful software that is great for digitizing all of your paper documents in one central location.
Please comment below if you have any questions about getting Paperless to run on your Raspberry Pi.
Be sure to check out our many other Raspberry Pi projects, including guides on using tools such as PhotoPrism.
