I’m writing this in response to this Paperless issue. The goal is to list out the complete installation procedure to install Paperless using Docker.
This will all be based on the official Paperless Docker installation documentation. I intend this to be used as a reference, it can be modified to suit your own needs.
You’re running Debian or Ubuntu and you’ve already installed docker, docker-compose, and git. If you’re not sure, run
apt install docker docker-compose git
Paperless works by watching a folder for files and processing any files that are placed in that folder. It makes sense that this folder would be shared in a local network, so that a scanner could save scanned documents to this share.
I will be assuming that this share is on the computer running Paperless located in
You are the root user.
Paperless will be installed to
I like to keep my docker-compose files in subdirectories of
/opt. You can put them anywhere you want.
At a basic level,
git clone just downloads a git repository. In this case, the git repo contains the Paperless application.
# cd /opt # git clone https://github.com/the-paperless-project/paperless.git # cd /opt/paperless
Paperless comes with example files for docker-compose. We will now copy the files that have the
.example suffix, and create the real files, which will not have that suffix.
# cp docker-compose.yml.example docker-compose.yml # cp docker-compose.env.example docker-compose.env
docker-compose.yml file is what the docker-compose program will read to set up Paperless. It’s a docker configuration file to run Paperless. The
docker-compose.env file is just a file that defines some variables that control how Paperless runs. Paperless decided to have a separate file for this.
Paperless is configured by editing the files we just created.
To make the changes, we will use the command-line text editor
nano. It’s very simple and intuitive, it behaves exactly how you would expect. To save and quit, press
Ctl + x, then
y, and last
First, let’s edit the
# nano docker-compose.yml
Now set the location of the Paperless consume directory. Edit Line 22 and Line 44. You will delete the “
./consume” and replace it with “
/mnt/sambashare/paperless-consume-directory”. The final line will look like:
# You have to adapt the local path you want the consumption # directory to mount to by modifying the part before the ':'. - /mnt/sambashare/paperless-consume-directory:/consume
Save and quit. Now we we will edit the
# nano docker-compose.env
Save and quit.
Now that the Paperless configuration is complete, we will now run Paperless with Docker.
Whenever you use any
docker-compose command, docker-compose will be reading the
docker-compose.yml file in your current directory. So in our case, any time you use
docker-compose with Paperless, you need to first make sure you are in the
# cd /opt/paperless
Once in this directory, you can start Paperless by running:
# docker-compose up -d
When you run this for the first time, you are going to witness some of the magic of Docker. An image is going to be built that’s already configured with everything Paperless needs to run. You don’t have to do any of those steps, you’re watching Docker do it for you. All you have to do is set set configuration options and Docker handles setting up the application.
Please note that I did get what looks like an error when running the above command. It appears that the installation hangs, but just give it a few minutes. In my testing, it the installation did not fail.
Installing dependencies from Pipfile.lock (6754ac)… Failed to load paths: /bin/sh: /root/.local/share/virtualenvs/paperless-fScSATYQ/bin/python: not found
In the end, you should see:
Creating paperless_webserver_1 ... done Creating paperless_consumer_1 ... done
Paperless should now be running. You can check by opening a web browser, and navigating to “http://<server_IP>:8000”. Replace “<server_IP>” with the actual IP of the machine running Paperless.
You should see the Paperless login page!
However, the administrator password has not been set. Go back to your SSH session, and run the following command:
# docker-compose run --rm webserver createsuperuser
That command will prompt you for a user name, an optional email address, and password.
After you run that command, you should be able to log in to Paperless.
The first big checkpoint is getting logged into Paperless. The next big checkpoint is making sure it can read and process files.
I made the assumption that you’ve already set up the network share. However you have that set up, put an image you would like to be processed in the paperless consumption directory. In this article, I’ve assumed that to be
In my assumption, I’m using a SMB share with Samba. I then point my scanner to save files to that SMB network share, in the
Once the file to be processed is in the consumption directory, Paperless should see it, and start processing it, which involves using an OCR program to try to parse the text. Give Paperless a couple of minutes, and your file should A) disappear from the consumption directory and B) appear in the Documents section of Paperless.
If this happens, then you are all set!
After you get everything working, I would encourage you to read this followup article where I go over some extra useful commands and configuration options.
If something isn’t working, the
docker-compose logs command would be useful to find errors.
All of this may look really complex, but once you have a basic understanding of shell commands and docker-compose, I promise you everything here is fairly basic. It looks like a lot because I go into detail about every step. It really just boils down to
git clone, edit the docker-compose files, and run using docker-compose.