From 491bbd571a31b7a53811c855cd03a8a8f95e47d1 Mon Sep 17 00:00:00 2001
From: Jonas Winkler <jonas.winkler@jpwinkler.de>
Date: Sat, 14 Nov 2020 14:16:57 +0100
Subject: [PATCH] more documentation
---
docs/administration.rst | 91 ++++++++++++++++++++++----------------
docs/advanced_usage.rst | 1 +
docs/configuration.rst | 6 ++-
docs/faq.rst | 29 +++++++++++-
docs/setup.rst | 97 ++++++++++++++++++++---------------------
docs/usage_overview.rst | 1 -
6 files changed, 135 insertions(+), 90 deletions(-)
diff --git a/docs/administration.rst b/docs/administration.rst
index 36e577443..a52d7753d 100644
--- a/docs/administration.rst
+++ b/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``
-on the directory containing the project files, and then rebuild the docker
-image.
+If a new release of paperless-ng is available, upgrading depends on how you
+installed paperless-ng in the first place. The releases are available at
+`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,
-updating paperless manually is somewhat more complicated.
+After grabbing the new release and unpacking the contents, do the following:
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
-
- $ 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.
+2. Collect static 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
-(TODO ref), you can use this command to move all your files after changing
+If you use paperless' feature to
+: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::
diff --git a/docs/advanced_usage.rst b/docs/advanced_usage.rst
index 1c4c6873c..3b48ea582 100644
--- a/docs/advanced_usage.rst
+++ b/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
##################
diff --git a/docs/configuration.rst b/docs/configuration.rst
index c11738b38..3ab233b3d 100644
--- a/docs/configuration.rst
+++ b/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.
\ No newline at end of file
+ needs.
+
+.. warning::
+
+ TBD: explain config options.
\ No newline at end of file
diff --git a/docs/faq.rst b/docs/faq.rst
index 9813a5d38..b55f5d058 100644
--- a/docs/faq.rst
+++ b/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.
\ No newline at end of file
+ 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.
diff --git a/docs/setup.rst b/docs/setup.rst
index 460e96cac..733ecbd0f 100644
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -6,13 +6,22 @@ Setup
Download
########
-The source is currently only available via GitHub, so grab it from there,
-by using ``git``:
+Go to the project page on GitHub and download the
+`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
-for you.
-
-The `docker route`_ is quick & easy.
+The `docker route`_ is quick & easy. This is the recommended route.
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``
- 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
+2. 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
- containers.
+4. Run ``docker-compose up -d``. This will create and start the necessary
+ 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
- :ref:`setup-sqlite_to_psql` for details.
+ ``docker-compose.sqlite.yml`` script instead, which does not use postgresql. See
+ :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.
-* The frontend needs to be built from source. The docker image takes care of
- that.
+ same, so you can just plug your old docker volumes into paperless-ng and
+ expect it to find everything where it should be.
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
- is done by:
+3. Download the latest release of paperless-ng. You can either go with the
+ 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
- $ git pull
+5. Update paperless. See :ref:`administration-updating` for details.
-3. If you are using docker, copy ``docker-compose.yml.example`` to
- ``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
+6. Start paperless-ng.
.. 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/
diff --git a/docs/usage_overview.rst b/docs/usage_overview.rst
index 344d1a1a5..dd9213a86 100644
--- a/docs/usage_overview.rst
+++ b/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
#################