more documentation

docs/administration.rst

@@ -3,13 +3,15 @@
 Administration
 **************
 
+.. _administration-backup:
 
 Making backups
 ##############
 
 .. warning::
 
-    This section is not updated to paperless-ng yet.
+    This section is not updated to paperless-ng yet, the exporter is a valid tool
+    for backups though.
 
 So you're bored of this whole project, or you want to make a remote backup of
 your files for whatever reason.  This is easy to do, simply use the
@@ -28,34 +30,61 @@ Restoring
 Updating paperless
 ##################
 
-For the most part, all you have to do to update Paperless is run ``git pull``
+If a new release of paperless-ng is available, upgrading depends on how you
-on the directory containing the project files, and then rebuild the docker
+installed paperless-ng in the first place. The releases are available at
-image.
+`release page <https://github.com/jonaswinkler/paperless-ng/releases>`_.
 
-.. code-block:: shell-session
+First of all, ensure that paperless is stopped.
+
+.. code:: shell-session
 
     $ cd /path/to/paperless
-    $ git pull
-
-If ``git pull`` doesn't report any changes, there is no need to continue with
-the remaining steps.
-
-After that, check if ``docker-compose.yml.example`` has changed. Update your
-``docker-compose.yml`` file if necessary.
-
-.. code-block:: shell-session
-
     $ docker-compose down
-    $ docker build -t jonaswinkler/paperless-ng .
-    $ docker-compose up -d
 
-The docker image will take care of database migrations during startup.
+After that, :ref:`make a backup <administration-backup>`.
+
+A.  If you used the docker-compose file, simply download the files of the new release,
+    adjust the settings in the files (i.e., the path to your consumption directory),
+    and replace your existing docker-compose files. Then start paperless as usual,
+    which will pull the new image, and update your database, if necessary:
+
+    .. code:: shell-session
+
+        $ cd /path/to/paperless
+        $ docker-compose up
+
+    If you see everything working, you can start paperless-ng with "-d" to have it
+    run in the background.
+
+B.  If you built the image yourself, grab the new archive and replace your current
+    paperless folder with the new contents.
+
+    After that, make the necessary adjustments to the docker-compose.yml (i.e.,
+    adjust your consumption directory).
+
+    Build and start the new image with:
+
+    .. code:: shell-session
+
+        $ cd /path/to/paperless
+        $ docker-compose build
+        $ docker-compose up
+
+    If you see everything working, you can start paperless-ng with "-d" to have it
+    run in the background.
+
+.. hint::
+
+    You can usually keep your ``docker-compose.env`` file, since this file will
+    never include mandantory configuration options. However, it is worth checking
+    out the new version of this file, since it might have new recommendations
+    on what to configure.
+
 
 Updating paperless without docker
 =================================
 
-Since paperless now involves a single page app that has to be built from source,
+After grabbing the new release and unpacking the contents, do the following:
-updating paperless manually is somewhat more complicated.
 
 1.  Update python requirements. Paperless uses
     `Pipenv`_ for managing dependencies:
@@ -68,28 +97,15 @@ updating paperless manually is somewhat more complicated.
 
     This creates a new virtual environment (or uses your existing environment)
     and installs all dependencies into it.
-    
-2.  You will also need to build the frontend each time a new update is pushed.
-    You need `npm <https://www.npmjs.com/get-npm>`_ for this.
 
-    .. code:: shell-session
+2.  Collect static files.
-
-        $ cd src-ui
-        $ npm install @angular/cli
-        $ ng build --prod
-    
-    This will build the application and move the relevant files to a location
-    within the django app (``src/documents/static/frontend``) at which django
-    expects to find the files.
-
-3.  Collect static files, namely the newly created frontend files.
 
     .. code:: shell-session
 
         $ cd src
         $ pipenv run python3 manage.py collectstatic --clear
     
-4.  Migrate the database.
+3.  Migrate the database.
 
     .. code:: shell-session
 
@@ -251,8 +267,9 @@ scheduler.
 Managing filenames
 ==================
 
-If you use paperless' feature to assign custom filenames to your documents
+If you use paperless' feature to
-(TODO ref), you can use this command to move all your files after changing
+:ref:`assign custom filenames to your documents <advanced-file_name_handling>`,
+you can use this command to move all your files after changing
 the naming scheme.
 
 .. warning::

docs/advanced_usage.rst

@@ -241,6 +241,7 @@ example, you can take a look at ``post-consumption-example.sh`` in the
 
 The post consumption script cannot cancel the consumption process.
 
+.. _advanced-file_name_handling:
 
 File name handling
 ##################

docs/configuration.rst

@@ -19,4 +19,8 @@ places.
         /usr/local/etc/paperless.conf
 
     Copy ``paperless.conf.example`` to any of these locations and adjust it to your
-    needs.
+    needs.
+
+.. warning::
+
+    TBD: explain config options.

docs/faq.rst

@@ -19,4 +19,31 @@ is
 
     Dont mess with this folder. Don't change permissions and don't move
     files around manually. This folder is meant to be entirely managed by docker
-    and paperless.
+    and paperless.
+
+**Q:** *Will paperless-ng run on Raspberry Pi?*
+
+**A:** The short answer is yes. The long answer is that certain parts of
+Paperless will run very slow, such as the tesseract OCR. On Rasperry Pi,
+try to OCR documents before feeding them into paperless so that paperless can
+reuse the text. The web interface should be alot snappier, since it runs
+in your browser and paperless has to do much less work to serve the data.
+
+**Q:** *How do I install paperless-ng on Raspberry Pi?*
+
+**A:** There is not docker image for ARM available. If you know how to build
+that automatically, I'm all ears. For now, you have to grab the latest release
+archive from the project page and build the image yourself. The release comes
+with the front end already compiled, so you don't have to do this on the Pi.
+
+You may encounter some issues during the build:
+
+.. code:: shell-session
+
+    W: GPG error: http://ports.ubuntu.com/ubuntu-ports focal InRelease: At least one invalid signature was encountered.
+    E: The repository 'http://ports.ubuntu.com/ubuntu-ports focal InRelease' is not signed.
+    N: Updating from such a repository can't be done securely, and is therefore disabled by default.
+    N: See apt-secure(8) manpage for repository creation and user configuration details.
+
+If this happens, look at `this thread <https://askubuntu.com/questions/1263284/>`:_.
+You will need to update docker to the latest version to fix this issue.

docs/setup.rst

@@ -6,13 +6,22 @@ Setup
 Download
 ########
 
-The source is currently only available via GitHub, so grab it from there,
+Go to the project page on GitHub and download the
-by using ``git``:
+`latest release <https://github.com/jonaswinkler/paperless-ng/releases>`_.
+There are multiple options available.
 
-.. code:: bash
+*   Download the docker-compose files if you want to pull paperless from
+    Docker Hub.
+
+*   Download the archive and extract it if you want to build the docker image
+    yourself or want to install paperless without docker.
+
+.. hint::
+
+    In contrast to paperless, the recommended way to get and update paperless-ng
+    is not to pull the entire git repository. Paperless-ng includes artifacts
+    that need to be compiled, and that's already done for you in the release.
 
-    $ git clone https://github.com/jonaswinkler/paperless-ng.git
-    $ cd paperless
 
 Installation
 ############
@@ -22,10 +31,7 @@ You can go multiple routes with setting up and running Paperless:
 * The `docker route`_
 * The `bare metal route`_
 
-The recommended setup route is docker, since it takes care of all dependencies
+The `docker route`_ is quick & easy. This is the recommended route.
-for you.
-
-The `docker route`_ is quick & easy.
 
 The `bare metal route`_ is more complicated to setup but makes it easier
 should you want to contribute some code back.
@@ -50,12 +56,7 @@ Docker Route
         .. _Docker installation guide: https://docs.docker.com/engine/installation/
         .. _docker-compose installation guide: https://docs.docker.com/compose/install/
 
-2.  Create a copy of ``docker-compose.yml.example`` as ``docker-compose.yml``
+2.  Modify ``docker-compose.yml`` to your preferences. You should change the path
-    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.
-3.  Modify ``docker-compose.yml`` to your preferences. You should change the path
     to the consumption directory in this file. Find the line that specifies where
     to mount the consumption directory:
 
@@ -72,7 +73,7 @@ Docker Route
     Don't change the part after the colon or paperless wont find your documents.
 
 
-4.  Modify ``docker-compose.env``, following the comments in the file. The
+3.  Modify ``docker-compose.env``, following the comments in the file. The
     most important change is to set ``USERMAP_UID`` and ``USERMAP_GID``
     to the uid and gid of your user on the host system. This ensures that
     both the docker container and you on the host machine have write access
@@ -80,10 +81,11 @@ Docker Route
     1000 (the default for the first normal user on most systems), it will
     work out of the box without any modifications.
 
-5. Run ``docker-compose up -d``. This will create and start the necessary
+4.  Run ``docker-compose up -d``. This will create and start the necessary
-   containers.
+    containers. This will also build the image of paperless if you grabbed the
+    source archive.
 
-6.  To be able to login, you will need a super user. To create it, execute the
+5.  To be able to login, you will need a super user. To create it, execute the
     following command:
 
     .. code-block:: shell-session
@@ -93,7 +95,7 @@ Docker Route
     This will prompt you to set a username, an optional e-mail address and
     finally a password.
 
-7.  The default ``docker-compose.yml`` exports the webserver on your local port
+6.  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 instance at ``http://127.0.0.1:8000``. You can login with the
     user and password you just created.
@@ -127,53 +129,48 @@ how you installed paperless. The important things to keep in mind are as follows
   with your current paperless media and data volumes and used the default
   sqlite database, **it will not use your sqlite database and it may seem
   as if your documents are gone**. You may use the provided
-  ``docker-compose.yml.sqlite.example`` script, which does not use postgresql. See
+  ``docker-compose.sqlite.yml`` script instead, which does not use postgresql. See
-  :ref:`setup-sqlite_to_psql` for details.
+  :ref:`setup-sqlite_to_psql` for details on how to move your data from
+  sqlite to postgres.
 * The task scheduler of paperless, which is used to execute periodic tasks
   such as email checking and maintenance, requires a `redis`_ message broker
   instance. The docker-compose route takes care of that.
 * The layout of the folder structure for your documents and data remains the
-  same.
+  same, so you can just plug your old docker volumes into paperless-ng and
-* The frontend needs to be built from source. The docker image takes care of
+  expect it to find everything where it should be.
-  that.
 
 Migration to paperless-ng is then performed in a few simple steps:
 
-1.  Do a backup for two purposes: If something goes wrong, you still have your
+1.  Stop paperless.
+
+    .. code:: bash
+
+        $ cd /path/to/current/paperless
+        $ docker-compose down
+
+2.  Do a backup for two purposes: If something goes wrong, you still have your
     data. Second, if you don't like paperless-ng, you can switch back to
     paperless.
 
-2.  Replace the paperless source with paperless-ng. If you're using git, this
+3.  Download the latest release of paperless-ng. You can either go with the
-    is done by:
+    docker-compose files or use the archive to build the image yourself.
+    You can either replace your current paperless folder or put paperless-ng
+    in a different location. Paperless-ng will use the same docker volumes
+    as paperless.
 
-    .. code:: bash
+4.  Adjust ``docker-compose.yml`` and
+    ``docker-compose.env`` to your needs.
+    See `docker route`_ for details on which edits are required.
 
-        $ git remote set-url origin https://github.com/jonaswinkler/paperless-ng
+5.  Update paperless. See :ref:`administration-updating` for details.
-        $ git pull
 
-3.  If you are using docker, copy ``docker-compose.yml.example`` to
+6.  Start paperless-ng.
-    ``docker-compose.yml`` and ``docker-compose.env.example`` to
-    ``docker-compose.env``. Make adjustments to these files as necessary.
-    See `docker route`_ for details.
-
-4.  Update paperless. See :ref:`administration-updating` for details.
-
-5.  Start paperless-ng.
-
-    .. code:: bash
-
-        $ docker-compose up
-        
-    This will also migrate your database as usual. Verify by inspecting the
-    output that the migration was successfully executed. CTRL-C will then
-    gracefully stop the container. After that, you can start paperless-ng as
-    usuall with 
 
     .. code:: bash
 
         $ docker-compose up -d
 
-6.  Paperless installed a permanent redirect to ``admin/`` in your browser. This
+7.  Paperless installed a permanent redirect to ``admin/`` in your browser. This
     redirect is still in place and prevents access to the new UI. Clear 
     everything related to paperless in your browsers data in order to fix
     this issue.
@@ -187,4 +184,4 @@ Moving data from sqlite to postgresql
 
     TBD.
 
-  .. _redis: https://redis.io/
+.. _redis: https://redis.io/

docs/usage_overview.rst

@@ -45,7 +45,6 @@ Each document has a couple of fields that you can assign to them:
   This text is fed into the search engine and is used for matching tags,
   correspondents and document types.
 
-.. TODO: hyperref
 
 Frontend overview
 #################