Documentation for easy Docker install

[chezmoa]

Hi everyone !

After trying many times to install Paperless with Docker, I exchanged few tweets with Daniel, who said me to put an issue for my problem.

My actual problem is that i am not a dev. ^^
It explain why i used Twitter before an issue. When you are not a developer make an issue is really not intuitive at all.

Docker is the same, in worst, for be honest, even if it is very powerfull, i fucking hate docker. I have a NAS wich run OMV, which had many plug-in before, and they disappeared on the latest version because docker is "more easy". Like the documentation of paperless say "The docker route is quick & easy.". Docker is never quick & easy for normal humans, end even few of my friends, who are dev as a job, say they hate it too.

By the way, even if i hate it, i learned the basic and how to use it. Now my NAS run 17 containers, some very easy (airsonic, handbrake) and others less easy (Nextcloud). My goal is to use as less as possible Command lines, wich i had to use with the Docker compose directly in Portainer for one container, and one time with SSH connection (for Open Project). But i had to use only one line for the container appear in Portainer just after.

Paperless is my biggest problems, i tryed over the Docker compose inside Portainer, but it ask me an array somewhere i didn't really understand. I searched on internet but the only few answers i found didn't work.

I know that paperless is free and i cannot ask it to be a one click installation. But if it is not possible to make the Docker install way more easy (without CLI i mean, and as less code as possible), could it be possible to have à step by step documentation, or a video tutorial which explain everything ? I learned how to use the basics of docker like this, with the video of TechnoDadLife and The duke of Puteaux.

Thanks in advance for your answers, and sorry for everyone who love Docker. ;-)

[maxfarrior]

i tryed over the Docker compose inside Portainer, but it ask me an array somewhere i didn't really understand. I searched on internet but the only few answers i found didn't work.

I just switched from a bare metal (LXC) install to a Docker install using docker-compose. I found the installation directions to be accurate.

I don't think Paperless in Docker is ever going to be a one-click type of thing. Understanding Docker so that you only have to edit a single docker-compose.yml file is IMO a lot easier than a bare-metal install.

It sounds like you're trying to use the docker-compose file in Portainer. What specific problem are you having?

[maxfarrior]

So I threw OMV in a VM, installed Docker and Portainer, and tried to get Paperless installed. I ran into several issues, and these issues really make it hard to have "really easy" installation directions.

First, Portainer does not support docker-compose files above version 2.0. I won't get into the why, but the docker-compose file that Paperless uses is version 2.4. One of the errors that Portainer gave was that the depends_on option must be an array. Each element in the array must also be a string. So the depends_on section should look like this:

...
        depends_on:
          - webserver
...

Also, the healthcheck option was introduced in docker-compose version 2.1. So that whole section needs to be removed.

The second issue I ran into is that the Paperless docker-compose file relies on several external files to work. The external files are docker-compose.env and Dockerfile, which are both located in the Paperless git repo. The docker-compose.env file can be worked around by removing the environment option from the docker-compose file, and specifying any environmental variables in Portainer (in the section below the docker-compose file). The bigger issue is that there's no way to provide the Dockerfile to Portainer. That file is needed in order to build the image that Paperless uses, I don't know of any solution to this.

The third issue I found is that OMV doesn't show you all the necessary information to define you consume directory. You will need to modify both consume lines to point to the actual place you want Paperless to read documents from. OMV doesn't show the full paths, but Shared Folders are located at /srv/dev-disk-by-label-<device_name>/<Shared_Folder>. The UID/GID that Paperless will use also needs to be set. I would create a user account for Paperless in OMV, and make sure that user has read/write permissions to wherever your Paperless consume directory lives. Then in a shell on OMV, look at the /etc/passwd file to see the UID and GID of the dedicated user. Last, in Portainer, make sure to specify the USERMAP_UID and USERMAP_GID environmental variables.

Portainer not supporting docker-compose version 2.4 (Dec 2017), is the biggest issue here. If Portainer supported version 2.4, you could feed the whole Paperless git repo to Portainer, and this would fix #1 and #2 above. You could then override the location of the consume directory with environmental variables, which addresses #3 above.

Paperless doesn't (and shouldn't) handle creating your consume directory or handling how that consume directory is shared. Because of that, there's never going to be a one-click installation method for Paperless, you're always going to have to do at least a little customization to match your own environment. Providing a git repo and a docker-compose file that you can edit, is probably the fastest and easiest way to distribute and install Paperless.

tl;dr: Going to the shell of OMV and using the Docker Installation Method is probably the best/easiest way to get Paperless installed.

[maxfarrior]

A couple of other potential ideas I thought may be worth mentioning:

Apparently you can create a one-node Docker Swarm in Portainer, and after doing this you can somehow use a docker-compose that supports version 3 files. Just something I briefly read, I don't know the details.

It also may be an option to manually build the Paperless image in Portainer, and then specify that image in your docker-compose file. That would address the biggest issue in my previous post.

Another idea I had is to clone the Paperless git repo and create/modify a docker-compose.yml file to work with version 2.0 (see changes in my last post). Then you may be able to give that new git repo to Portainer using the "git repository" option on the "Add Stack" menu.

IMO, all those options are still more difficult that just using the already-documented Docker directions.

[chezmoa]

Hi !

Thanks to all for the answers !

If no one click install is possible, is something with less line in CLI possible ?
I was surprise how Open Project was easy to install over CLI while it was big shit to install in OMV. But i understand it is not the same system with paperless.

So if the docker actual way is the only solution, is it possible to write à very friendly user tutorial.
For example the point 3 say :

Create a copy of docker-compose.yml.example as docker-compose.yml and a copy of docker-compose.env.example as docker-compose.env. You’ll be editing both these files: taking a copy ensures that you can git pull to receive updates without risking merge conflicts with your modified versions of the configuration files.

When i read this point i ask me many questions :

• How do i copy this files ?
• Where do i copy them ?
• How do i edit them ?
• I am lost with the git pull thing
• etc

I have few basics in docker but it is still difficult for me to understand everything if it is not a step by step guide.
I also love step by step guide which explain things, it is a good way to learn, but a simple guide is enough too.

The paperless project look like one of easiest to use tool for be paperless (the only more easy i know is paperwork but it is a local one computer system). I hope after the install will be done the difficult part will be over.

Thanks to all for your answers

[maxfarrior]

I see what you are saying. But unfortunately, I don't think it's ever going to be that easy.

First, the location of the Paperless consume directory is going to be different for every person. And just due to this, you're going to have to make a customization that's specific to you. A generic solution won't work for everybody.

Second, the basics of shell usage is assumed. In my opinion, it's out of the scope of Paperless to tell you where to put your files or how to copy them. Paperless can't walk you through everything. Some people may then ask "how do I connect with SSH?" or "how do I install Linux so I can run this?" You'd probably agree that Paperless shouldn't go over those things.

I don't want to be insensitive here. I completely understand where you are coming from and the whole reason I responded was to see if I could help make it easier for you.

In the Open Project link you posted, there are two steps to get it working are a git clone and a docker-compose up. The Paperless documentation does these same steps, but it doesn't appear that way. Paperless don't give you a docker compose file already, it gives you an example file, and it has you edit the example files to fit your needs. The Paperless docs also goes over the different configurable options you can set. This is why there's so many steps. But at its core, you download Paperless from its git repo, edit the docker-compose file, and run it.

I think the issues you are having are outside of the scope of the Paperless application. The ability to do basic tasks in a shell are assumed. I also don't think there is any way to make the installation any easier (without requiring a crazy amount of dev effort).

To help you and other people in your situation, I'll write something up that gives all the steps to get Paperless working in Docker. Give me some time on that.

[maxfarrior]

Alright. I wrote out the process of running Paperless using Docker. I posted it on my website.

The directions were intended to be generic, so it's not specifc to OMV. That said, I did test them on OMV. Two OMV-specific points:

• Refer to the third issue in my earlier post to find the location of your Paperless consume directory. In my OMV VM, I made a SMB share and created a folder for Paperless in that. My location ended up being /srv/dev-disk-by-label-StoragePool/FamilyFolder/paperless-consume.

  • StoragePool is the Raid device in the Raid Management section
  • FamilyFolder is the name of the Shared Folder
  • paperless-consume is a folder I made after connecting to the SMB share from my computer

• Also, OMV apparent uses port 8000 for some docker-related proxy service. So you will have to run Paperless on a different port. When you're editing the docker-compose.yml file, on Line 11, change the first 8000 to something else. I used 7000. And when you access Paperless in your web browser, use "http://<server_IP>:7000"

Let me know if any parts are not clear.

[chezmoa]

Hi !

THAT WAS PERFECT !

Thanks fort all your time. Your step by step guide was really easy to use.

Just few things i did after :

• I didn't know exactely wich user in OMV needed to acces the share folder, so i gave acces to all to this one (in any case i am the only one who use my NAS).

• In OMV the OS is on a different disk than datas. The docker containers are install on the OS disk, but the consume directory is on the data disk. On that way the files i put in the consume directory disapear, was add to the paperless webserver, but was then moved to a media folder on the OS drive (i don't even really know where). I changed the media directory in docker for replace it by my data disk.
  The goal is to can make a backup of the OS with all the parameter (like docker) with using the Clonezilla service in the OMV, and let the docs (after consume) on a data disk (or on RAID like i have).
  Should i also change the data directory for be more clean on that way to do ?

• SSL was easy to do for can acces from outside, and the android app look like working too.

• I add the optional PAPERLESS_INLINE_DOC=true from your second article, it was even more easy to do over portainer.

Now i just have to learn how to use Paperless with script and IMAP for make it super powerful (even if it is already).

Thanks to everyone who helped !

Next time i will open an issue, i think it will be for help too. I can see there is no french translation for the moment, maybe i can help with that. :-)