From 4862ce767461acb45aa38cd826deb199124f4ab6 Mon Sep 17 00:00:00 2001 From: Jonas Winkler Date: Fri, 13 Nov 2020 20:30:33 +0100 Subject: [PATCH] more documentation. --- docs/administration.rst | 96 ++++++++++++++++++++--------------------- docs/advanced_usage.rst | 81 ++++++++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+), 48 deletions(-) diff --git a/docs/administration.rst b/docs/administration.rst index 9f1ecd122..44b4d2ade 100644 --- a/docs/administration.rst +++ b/docs/administration.rst @@ -27,75 +27,74 @@ Restoring Updating paperless ################## -.. warning:: - - This section is not updated yet. - 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 use Django's -``migrate`` command to execute any database schema updates that might have been -rolled in as part of the update: +on the directory containing the project files, and then rebuild the docker +image. .. code-block:: shell-session - $ cd /path/to/project + $ cd /path/to/paperless $ git pull - $ pip install -r requirements.txt - $ cd src - $ ./manage.py migrate -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. - -Additionally, as new features are added, the ability to control those features -is typically added by way of an environment variable set in ``paperless.conf``. -You may want to take a look at the ``paperless.conf.example`` file to see if -there's anything new in there compared to what you've got in ``/etc``. +If ``git pull`` doesn't report any changes, there is no need to continue with +the remaining steps. -If you are using docker the update process is similar: +After that, check if ``docker-compose.yml.example`` has changed. Update your +``docker-compose.yml`` file if necessary. .. code-block:: shell-session - $ cd /path/to/project - $ git pull - $ docker build -t paperless . - $ docker-compose run --rm consumer migrate + $ docker-compose down + $ docker build -t jonaswinkler/paperless-ng . $ docker-compose up -d -If ``git pull`` doesn't report any changes, there is no need to continue with -the remaining steps. +The docker image will take care of database migrations during startup. -This depends on the route you've chosen to run paperless. +Updating paperless without docker +================================= - a. If you are not using docker, update python requirements. Paperless uses - `Pipenv`_ for managing dependencies: +Since paperless now involves a single page app that has to be built from source, +updating paperless manually is somewhat more complicated. - .. code:: bash +1. Update python requirements. Paperless uses + `Pipenv`_ for managing dependencies: - $ pip install --upgrade pipenv - $ cd /path/to/paperless - $ pipenv install + .. code:: shell-session - This creates a new virtual environment (or uses your existing environment) - and installs all dependencies into it. Running commands inside the environment - is done via + $ pip install --upgrade pipenv + $ cd /path/to/paperless + $ pipenv install - .. code:: bash + 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 `_ for this. - $ cd /path/to/paperless/src - $ pipenv run python3 manage.py my_command - - You will also need to build the frontend each time a new update is pushed. - See updating paperless for more information. TODO REFERENCE - - b. If you are using docker, build the docker image. + .. 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. - .. code:: bash + .. code:: shell-session - $ docker build -t jonaswinkler/paperless-ng:latest . + $ cd src + $ pipenv run python3 manage.py migrate - Copy either docker-compose.yml.example or docker-compose.yml.sqlite.example - to docker-compose.yml and adjust the consumption directory. Management utilities #################### @@ -246,6 +245,7 @@ the index and usually makes queries faster and also ensures that the autocompletion works properly. This command is regularly invoked by the task scheduler. +.. _utilities-renamer: Managing filenames ================== @@ -269,7 +269,7 @@ The command takes no arguments and processes all your documents at once. .. _utilities-encyption: -Managing encrpytion +Managing encryption =================== Documents can be stored in Paperless using GnuPG encryption. diff --git a/docs/advanced_usage.rst b/docs/advanced_usage.rst index 7ddccd2aa..1c4c6873c 100644 --- a/docs/advanced_usage.rst +++ b/docs/advanced_usage.rst @@ -240,3 +240,84 @@ example, you can take a look at ``post-consumption-example.sh`` in the ``scripts`` directory in this project. The post consumption script cannot cancel the consumption process. + + +File name handling +################## + +By default, paperless stores your documents in the media directory and renames them +using the identifier which it has assigned to each document. You will end up getting +files like ``0000123.pdf`` in your media directory. This isn't necessarily a bad +thing, because you normally don't have to access these files manually. However, if +you wish to name your files differently, you can do that by adjustng the +``PAPERLESS_FILENAME_FORMAT`` settings variable. + +This variable allows you to configure the filename (folders are allowed!) using +placeholders. For example, setting + +.. code:: bash + + PAPERLESS_FILENAME_FORMAT={created_year}/{correspondent}/{title} + +will create a directory structure as follows: + +.. code:: + + 2019/ + my_bank/ + statement-january-0000001.pdf + statement-february-0000002.pdf + 2020/ + my_bank/ + statement-january-0000003.pdf + shoe_store/ + my_new_shoes-0000004.pdf + +Paperless appends the unique identifier of each document to the filename. This +avoides filename clashes. + +.. danger:: + + Do not manually move your files in the media folder. Paperless remembers the + last filename a document was stored as. If you do rename a file, paperless will + report your files as missing and won't be able to find them. + +Paperless provides the following placeholders withing filenames: + +* ``{correspondent}``: The name of the correspondent, or "none". +* ``{title}``: The title of the document. +* ``{created}``: The full date and time the document was created. +* ``{created_year}``: Year created only. +* ``{created_month}``: Month created only (number 1-12). +* ``{created_day}``: Day created only (number 1-31). +* ``{added}``: The full date and time the document was added to paperless. +* ``{added_year}``: Year added only. +* ``{added_month}``: Month added only (number 1-12). +* ``{added_day}``: Day added only (number 1-31). +* ``{tags}``: I don't know how this works. Look at the source. + +Paperless will convert all values for the placeholders into values which are safe +for use in filenames. + +.. hint:: + + Paperless checks the filename of a document whenever it is saved. Therefore, + you need to update the filenames of your documents and move them after altering + this setting by invoking the :ref:`document renamer `. + +.. warning:: + + Make absolutely sure you get the spelling of the placeholders right, or else + paperless will use the default naming scheme instead. + +.. caution:: + + As of now, you could totally tell paperless to store your files anywhere outside + the media directory by setting + + .. code:: + + PAPERLESS_FILENAME_FORMAT=../../my/custom/location/{title} + + However, keep in mind that inside docker, if files get stored outside of the + predefined volumes, they will be lost after a restart of paperless.