Add Dockerfile for application and documentation

This commit adds a `Dockerfile` to the root of the project, accompanied
by a `docker-compose.yml.example` for simplified deployment. The
`Dockerfile` is agnostic to whether it will be the webserver, the
consumer, or if it is run for a one-off command (i.e. creation of a
superuser, migration of the database, document export, ...).

The containers entrypoint is the `scripts/docker-entrypoint.sh` script.
This script verifies that the required permissions are set, remaps the
default users and/or groups id if required and installs additional
languages if the user wishes to.

After initialization, it analyzes the command the user supplied:

  - If the command starts with a slash, it is expected that the user
    wants to execute a binary file and the command will be executed
    without further intervention. (Using `exec` to effectively replace
    the started shell-script and not have any reaping-issues.)

  - If the command does not start with a slash, the command will be
    passed directly to the `manage.py` script without further
    modification. (Again using `exec`.)

The default command is set to `--help`.

If the user wants to execute a command that is not meant for `manage.py`
but doesn't start with a slash, the Docker `--entrypoint` parameter can
be used to circumvent the mechanics of `docker-entrypoint.sh`.

Further information can be found in `docs/setup.rst` and in
`docs/migrating.rst`.

For additional convenience, a `Dockerfile` has been added to the `docs/`
directory which allows for easy building and serving of the
documentation. This is documented in `docs/requirements.rst`.

.gitignore

@@ -68,6 +68,7 @@ db.sqlite3
 # Other stuff that doesn't belong
 virtualenv
 .vagrant
+docker-compose.yml
 
 # Used for development
 scripts/import-for-development

Dockerfile

@@ -0,0 +1,43 @@
+FROM python:3.5.1
+MAINTAINER Pit Kleyersburg <[email protected]>
+
+# Install dependencies
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        sudo \
+        tesseract-ocr tesseract-ocr-eng imagemagick ghostscript \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install python dependencies
+RUN mkdir -p /usr/src/paperless
+WORKDIR /usr/src/paperless
+COPY requirements.txt /usr/src/paperless/
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application
+RUN mkdir -p /usr/src/paperless/src
+COPY src/ /usr/src/paperless/src/
+
+# Set consumption directory
+ENV PAPERLESS_CONSUME /consume
+RUN mkdir -p $PAPERLESS_CONSUME
+
+# Migrate database
+WORKDIR /usr/src/paperless/src
+RUN mkdir /usr/src/paperless/data
+RUN ./manage.py migrate
+
+# Create user
+RUN groupadd -g 1000 paperless \
+    && useradd -u 1000 -g 1000 -d /usr/src/paperless paperless \
+    && chown -Rh paperless:paperless /usr/src/paperless
+
+# Setup entrypoint
+COPY scripts/docker-entrypoint.sh /sbin/docker-entrypoint.sh
+RUN chmod 755 /sbin/docker-entrypoint.sh
+
+# Mount volumes
+VOLUME ["/usr/src/paperless/data", "/usr/src/paperless/media", "/consume"]
+
+ENTRYPOINT ["/sbin/docker-entrypoint.sh"]
+CMD ["--help"]

docker-compose.env

@@ -0,0 +1,15 @@
+# Environment variables to set for Paperless
+# Commented out variables will be replaced by a default within Paperless.
+
+# Passphrase Paperless uses to encrypt and decrypt your documents
+PAPERLESS_PASSPHRASE=CHANGE_ME
+
+# The amount of threads to use for text recognition
+# PAPERLESS_OCR_THREADS=4
+
+# Additional languages to install for text recognition
+# PAPERLESS_OCR_LANGUAGES=deu ita
+
+# You can change the default user and group id to a custom one
+# USERMAP_UID=1000
+# USERMAP_GID=1000

docker-compose.yml.example

@@ -0,0 +1,31 @@
+version: '2'
+
+services:
+    webserver:
+        image: paperless
+        ports:
+            # You can adapt the port you want Paperless to listen on by
+            # modifying the part before the `:`.
+            - "8000:8000"
+        volumes:
+            - paperless-data:/usr/src/paperless/data
+            - paperless-media:/usr/src/paperless/media
+        env_file: docker-compose.env
+        environment:
+            - PAPERLESS_OCR_LANGUAGES=
+        command: ["runserver", "0.0.0.0:8000"]
+
+    consumer:
+        image: paperless
+        volumes:
+            - paperless-data:/usr/src/paperless/data
+            - paperless-media:/usr/src/paperless/media
+            # You have to adapt the local path you want the consumption
+            # directory to mount to by modifying the part before the ':'.
+            - /path/to/arbitrary/place:/consume
+        env_file: docker-compose.env
+        command: ["document_consumer"]
+
+volumes:
+    paperless-data:
+    paperless-media:

docs/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.5.1
+MAINTAINER Pit Kleyersburg <[email protected]>
+
+# Install Sphinx and Pygments
+RUN pip install Sphinx Pygments
+
+# Setup directories, copy data
+RUN mkdir /build
+COPY . /build
+WORKDIR /build/docs
+
+# Build documentation
+RUN make html
+
+# Start webserver
+WORKDIR /build/docs/_build/html
+EXPOSE 8000/tcp
+CMD ["python3", "-m", "http.server"]

docs/migrating.rst

@@ -30,6 +30,20 @@ as part of the update:
 Note that it's possible (even likely) that while ``git pull`` may update some
 files, the ``migrate`` step may not update anything.  This is totally normal.
 
+If you are :ref:`using Docker <setup-installation-docker>` the update process
+requires only one additional step:
+
+.. code-block:: shell-session
+
+    $ cd /path/to/project
+    $ git pull
+    $ docker build -t paperless .
+    $ docker-compose up -d
+    $ docker-compose run --rm webserver migrate
+
+If ``git pull`` doesn't report any changes, there is no need to continue with
+the remaining steps.
+
 
 .. _migrating-backup:
 
@@ -53,6 +67,65 @@ with Django's ``dumpdata`` command, which produces JSON output.
     $ ./manage.py document_export /path/to/arbitrary/place/
     $ ./manage.py dumpdata documents.Tag > /path/to/arbitrary/place/tags.json
 
+If you are :ref:`using Docker <setup-installation-docker>`, exporting your tags
+as JSON is almost as easy:
+
+.. code-block:: shell-session
+
+    $ docker-compose run --rm webserver dumpdata documents.Tag > /path/to/arbitrary/place/tags.json
+
+Exporting the documents though is a little more involved, since docker-compose
+doesn't support mounting additional volumes with the ``run`` command. You have
+three general options:
+
+1. Use the consumption directory if you happen to already have it mounted to a
+   host directory.
+
+   .. code-block:: console
+
+       $ # Stop the consumer so that it doesn't consume the exported documents
+       $ docker-compose stop consumer
+       $ # Export into the consumption directory
+       $ docker-compose run --rm consumer document_exporter /consume
+
+2. Add another volume to ``docker-compose.yml`` for exports and use
+   ``docker-compose run``:
+
+   .. code-block:: diff
+
+      diff --git a/docker-compose.yml b/docker-compose.yml
+      --- a/docker-compose.yml
+      +++ b/docker-compose.yml
+      @@ -17,9 +18,8 @@ services:
+               volumes:
+                   - paperless-data:/usr/src/paperless/data
+                   - paperless-media:/usr/src/paperless/media
+                   - /consume
+      +            - /path/to/arbitrary/place:/export
+
+   .. code-block:: shell-session
+
+       $ docker-compose run --rm consumer document_exporter /export
+
+3. Use ``docker run`` directly, supplying the necessary commandline options:
+
+   .. code-block:: shell-session
+
+       $ # Identify your containers
+       $ docker-compose ps
+               Name                       Command                State     Ports
+       -------------------------------------------------------------------------
+       paperless_consumer_1    /sbin/docker-entrypoint.sh ...   Exit 0
+       paperless_webserver_1   /sbin/docker-entrypoint.sh ...   Exit 0
+
+       $ # Make sure to replace your passphrase and remove or adapt the id mapping
+       $ docker run --rm \
+           --volumes-from paperless_data_1 \
+           --volume /path/to/arbitrary/place:/export \
+           -e PAPERLESS_PASSPHRASE=YOUR_PASSPHRASE \
+           -e USERMAP_UID=1000 -e USERMAP_GID=1000 \
+           paperless document_exporter /export
+
 
 .. _migrating-restoring:
 
@@ -77,3 +150,25 @@ exported documents into the consumption directory and start up the consumer.
     $ cp /path/to/exported/docs/* /path/to/consumption/dir/
     $ ./manage.py document_consumer
 
+Importing your data if you are :ref:`using Docker <setup-installation-docker>`
+is almost as simple:
+
+.. code-block:: shell-session
+
+    $ # Stop and remove your current containers
+    $ docker-compose stop
+    $ docker-compose rm -f
+
+    $ # Recreate them, add the superuser
+    $ docker-compose up -d
+    $ docker-compose run --rm webserver createsuperuser
+
+    $ # Load the tags
+    $ cat /path/to/arbitrary/place/tags.json | docker-compose run --rm webserver loaddata_stdin -
+
+    $ # Load your exported documents into the consumption directory
+    $ # (How you do this highly depends on how you have set this up)
+    $ cp /path/to/exported/docs/* /path/to/mounted/consumption/dir/
+
+After loading the documents into the consumption directory the consumer will
+immediately start consuming the documents.

docs/requirements.rst

@@ -101,3 +101,16 @@ you'd like to generate your own docs locally, you'll need to:
     $ pip install sphinx
 
 and then cd into the ``docs`` directory and type ``make html``.
+
+If you are using Docker, you can use the following commands to build the
+documentation and run a webserver serving it on `port 8001`_:
+
+.. code:: bash
+
+    $ pwd
+    /path/to/paperless
+
+    $ docker build -t paperless:docs -f docs/Dockerfile .
+    $ docker run --rm -it -p "8001:8000" paperless:docs
+
+.. _port 8001: http://127.0.0.1:8001