Merge pull request #50 from tikitu/docker-tweaks

Some small tweaks to the Docker setup and documentation

.gitignore

@@ -69,6 +69,7 @@ db.sqlite3
 virtualenv
 .vagrant
 docker-compose.yml
+docker-compose.env
 
 # Used for development
 scripts/import-for-development

docker-compose.yml.example

@@ -23,6 +23,12 @@ services:
             # 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
+            # Likewise, you can add a local path to mount a directory for
+            # exporting. This is not strictly needed for paperless to
+            # function, only if you're exporting your files: uncomment
+            # it and fill in a local path if you know you're going to 
+            # want to export your documents.
+            # - /path/to/another/arbitrary/place:/export
         env_file: docker-compose.env
         command: ["document_consumer"]
 

docs/migrating.rst

@@ -74,57 +74,37 @@ as JSON is almost as easy:
 
     $ 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:
+To export the documents you can either use ``docker run`` directly, specifying all
+the commandline options by hand, or (more simply) mount a second volume for export.
 
-1. Use the consumption directory if you happen to already have it mounted to a
-   host directory.
+To mount a volume for exports, follow the instructions in the
+``docker-compose.yml.example`` file for the ``/export`` volume (making the changes
+in your own ``docker-compose.yml`` file, of course). Once you have the
+volume mounted, the command to run an export is:
 
-   .. code-block:: console
+.. 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
+   $ docker-compose run --rm consumer document_exporter /export
 
-2. Add another volume to ``docker-compose.yml`` for exports and use
-   ``docker-compose run``:
+If you prefer to use ``docker run`` directly, supplying the necessary commandline
+options:
 
-   .. code-block:: diff
+.. code-block:: shell-session
 
-      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
+   $ # 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
 
-   .. 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
+   $ # 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:

docs/setup.rst

@@ -156,8 +156,15 @@ Docker Method
        .. _Docker installation guide: https://docs.docker.com/engine/installation/
        .. _docker-compose installation guide: https://docs.docker.com/compose/install/
 
-3. Create a copy of ``docker-compose.yml.example`` as ``docker-compose.yml``.
-4. Modify ``docker-compose.env`` and adapt the following environment variables:
+3. 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.
+4. Modify ``docker-compose.yml`` to your preferences, following the instructions
+   in comments in the file. The only change that is a hard requirement is to 
+   specify where the consumption directory should mount.
+5. Modify ``docker-compose.env`` and adapt the following environment variables:
 
    ``PAPERLESS_PASSPHRASE``
      This is the passphrase Paperless uses to encrypt/decrypt the original
@@ -186,9 +193,9 @@ Docker Method
      and thus the one of the consumption directory. Furthermore, you can change
      the id of the default user as well using ``USERMAP_UID``.
 
-5. Run ``docker-compose up -d``. This will create and start the necessary
+6. Run ``docker-compose up -d``. This will create and start the necessary
    containers.
-6. To be able to login, you will need a super user. To create it, execute the
+7. To be able to login, you will need a super user. To create it, execute the
    following command:
 
    .. code-block:: shell-session
@@ -197,11 +204,11 @@ Docker Method
 
    This will prompt you to set a username (default ``paperless``), an optional
    e-mail address and finally a password.
-7. The default ``docker-compose.yml`` exports the webserver on your local port
+8. The default ``docker-compose.yml`` exports the webserver on your local port
    8000. If you haven't adapted this, you should now be able to visit your
    `Paperless webserver`_ at ``http://127.0.0.1:8000``. You can login with the
    user and password you just created.
-8. Add files to consumption directory the way you prefer to. Following are two
+9. Add files to consumption directory the way you prefer to. Following are two
    possible options:
 
    1. Mount the consumption directory to a local host path by modifying your