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:
@@ -69,27 +98,14 @@ 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.
+2.  Collect static files.
-    You need `npm <https://www.npmjs.com/get-npm>`_ for this.
-
-    .. code:: shell-session
-
-        $ 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

@@ -20,3 +20,7 @@ places.
 
     Copy ``paperless.conf.example`` to any of these locations and adjust it to your
     needs.
+
+.. warning::
+
+    TBD: explain config options.

docs/faq.rst

@@ -20,3 +20,30 @@ 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.
+
+**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.

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