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.

Assumptions

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 /mnt/sambashare/paperless-consume-directory.
You are the root user.
Paperless will be installed to /opt/paperless.

Download the Paperless application

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

The 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.

Configure Paperless

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 enter.

First, let’s edit the docker-compose.yml file.

# 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 docker-compose.env file.

# nano docker-compose.env

You probably want to change the time zone on Line 15. Remove the # from the line and replace America/Los_Angeles with your own value. All available values can be found on this Wikipedia page.

Save and quit.

Starting Paperless with Docker

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 /opt/paperless directory.

# 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.

Testing Paperless Consumption

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 /mnt/sambashare/paperless-consumption-directory.

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 paperless-consumption-directory folder.

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!

Final Words

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.

Installing Paperless in Docker

Categories