lgcosta/paperless-ngx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Squashed commit of the following:

Browse Source 
commit b1410a854e
Merge: f9ce4d8f 8ec9c77e
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Thu Dec 29 20:09:09 2022 -0800

    Merge pull request #2263 from paperless-ngx/v1.11.0-changelog

    [Documentation] Add v1.11.0 changelog

commit 8ec9c77e51
Author: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Date:   Fri Dec 30 04:08:17 2022 +0000

    Changelog v1.11.0 - GHA

commit f9ce4d8f6a
Author: Michael Shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Thu Dec 29 19:40:25 2022 -0800

    Update version strings for 1.11.0

commit 8c9a74ee0c
Merge: 605f86f0 0b59ef2c
Author: Michael Shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Thu Dec 29 19:39:38 2022 -0800

    Merge branch 'dev'

commit 605f86f0cf
Merge: 800e842a 8cbaca22
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Wed Dec 28 15:55:35 2022 -0800

    Merge pull request #2256 from mendelk/patch-1

    Fixed typo in docs

commit 8cbaca22c1
Author: Mendel Kramer <mendelk@users.noreply.github.com>
Date:   Wed Dec 28 18:16:00 2022 -0500

    Fixed typo in docs

commit 800e842ab3
Author: ThellraAK <github.com@absurdlybored.com>
Date:   Wed Dec 21 01:36:37 2022 -0900

    Removing Mariadb default open port (#2227)

    * Removing Mariadb default open port

    Removing the listening port 3306 for the DB, Docker networks will let the containers talk to one another.  The existing setup would allow anyone to connect to the DB and use the default passwords.

    * Update docker-compose.mariadb-tika.yml

    Adding change to the other compose file to remove open port

    * Remove excess blank lines

    * Remove excess blank lines

    Co-authored-by: Felix E <felix@eckhofer.com>

commit 6f6f365e2b
Merge: 6d324dbd 43b863b8
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Sat Dec 17 19:58:06 2022 -0800

    Merge pull request #2203 from tooomm/docs_updates

    Docs: More fixes and improvements

commit 43b863b816
Author: tooomm <tooomm@users.noreply.github.com>
Date:   Sun Dec 11 19:44:18 2022 +0100

    doc fixes

    This reverts commit e015babdc102a65a3cce0cc71812d3eb730da92e.

    link fix

    fix escaping, spacing, profile links, typo

    revert

    ~~add~~ at fixes

    Revert "~~add~~ at fixes"

    This reverts commit ce0192b733c19614048de81ea917660e25bb35f2.

commit 6d324dbd8e
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Fri Dec 16 09:10:11 2022 -0800

    Update config.yml

commit 8ddf05e573
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Fri Dec 16 09:09:48 2022 -0800

    Update bug-report.yml

commit 0472dfe25a
Author: tooomm <tooomm@users.noreply.github.com>
Date:   Sun Dec 11 19:12:58 2022 +0100

    Docs: Fix leftover issues from conversion (#2172)

commit 8b36c9ad64
Author: tooomm <tooomm@users.noreply.github.com>
Date:   Sun Dec 11 16:07:08 2022 +0100

    more fixes and cleanup

commit 1266f2d5b9
Author: tooomm <tooomm@users.noreply.github.com>
Date:   Sun Dec 11 12:06:15 2022 +0100

    fix links

commit 8196051959
Merge: 06a6eb03 d198142a
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Fri Dec 9 16:12:20 2022 -0800

    Merge pull request #2157 from Weltraumschaf/patch-1

    Update setup.md

commit d198142a1e
Author: Sven Strittmatter <ich@weltraumschaf.de>
Date:   Fri Dec 9 22:09:06 2022 +0100

    Update setup.md

    W/o the slash it resolves to /setup/configuration/ which does 404.

commit 06a6eb0326
Author: Michael Shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Fri Dec 9 08:15:03 2022 -0800

    fix code block indentation

commit 28819d6d0f
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Fri Dec 9 08:11:42 2022 -0800

    Fix code block indentation

commit 8cd5e25364
Merge: 32d54674 7788d932
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Tue Dec 6 11:23:15 2022 -0800

    Merge pull request #2137 from paperless-ngx/more-docs-cleanup

    Chore: Cleanup of new documentation

commit 7788d93227
Author: Trenton Holmes <797416+stumpylog@users.noreply.github.com>
Date:   Sun Dec 4 08:34:49 2022 -0800

    Further cleanup of docs, including fixing autoconvert issues and general cleanups

commit 32d546740b
Merge: b0ca57a7 24da3e50
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Sun Dec 4 19:12:27 2022 -0800

    Merge pull request #2118 from alexander-bauer/chart-bump

commit 24da3e5034
Author: Alexander Bauer <sasha@linux.com>
Date:   Mon Dec 5 02:51:35 2022 +0000

    Bump Helm Chart version to trigger release

commit b0ca57a7f0
Merge: cdd49c51 c864b3cd
Author: shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Sun Dec 4 14:36:00 2022 -0800

    Merge pull request #2114 from paperless-ngx/v1.10.2-changelog

    [Documentation] Add v1.10.2 changelog

commit cdd49c5142
Author: Michael Shamoon <4887959+shamoon@users.noreply.github.com>
Date:   Sun Dec 4 14:32:08 2022 -0800

    Update frontend compilation info

commit c864b3cd19
Author: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Date:   Sun Dec 4 21:17:16 2022 +0000

    Changelog v1.10.2 - GHA
This commit is contained in:
Michael Shamoon
2022-12-29 20:09:58 -08:00
parent dcc4146b66
commit 9e875202f4
19 changed files with 344 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/advanced_usage.md
View File

@@ -50,7 +50,7 @@ and run another document through the consumer. Once complete, you should
see the newly-created document, automatically tagged with the
appropriate data.
### Automatic matching {#automatic_matching}
### Automatic matching {#automatic-matching}
Paperless-ngx comes with a new matching algorithm called _Auto_. This
matching algorithm tries to assign tags, correspondents, document types,
@@ -59,8 +59,8 @@ assigned these on existing documents. It uses a neural network under the
hood.
If, for example, all your bank statements of your account 123 at the
Bank of America are tagged with the tag "bofa*123" and the matching
algorithm of this tag is set to \_Auto*, this neural network will examine
Bank of America are tagged with the tag "bofa123" and the matching
algorithm of this tag is set to _Auto_, this neural network will examine
your documents and automatically learn when to assign this tag.
Paperless tries to hide much of the involved complexity with this
@@ -95,7 +95,7 @@ when using this feature:
of these correspondents to ANY new document, if both are set to
automatic matching.
## Hooking into the consumption process
## Hooking into the consumption process {#consume-hooks}
Sometimes you may want to do something arbitrary whenever a document is
consumed. Rather than try to predict what you may want to do, Paperless
@@ -115,7 +115,7 @@ and then put the path to that script in `paperless.conf` or
asynchronously, you'll have to fork the process in your script and
exit.
### Pre-consumption script
### Pre-consumption script {#pre-consume-script}
Executed after the consumer sees a new document in the consumption
folder, but before any processing of the document is performed. This
@@ -151,7 +151,7 @@ with the newly modified file.
The script's stdout and stderr will be logged line by line to the
webserver log, along with the exit code of the script.
### Post-consumption script {#post_consume_script}
### Post-consumption script {#post-consume-script}
Executed after the consumer has successfully processed a document and
has moved it into paperless. It receives the following environment
@@ -181,33 +181,34 @@ The post consumption script cannot cancel the consumption process.
The script's stdout and stderr will be logged line by line to the
webserver log, along with the exit code of the script.
#### Docker
### Docker {#docker-consume-hooks}
Assumed you have
`/home/foo/paperless-ngx/scripts/post-consumption-example.sh`.
To hook into the consumption process when using Docker, you
will need to pass the scripts into the container via a host mount
in your `docker-compose.yml`.
You can pass that script into the consumer container via a host mount in
your `docker-compose.yml`.
Assuming you have
`/home/paperless-ngx/scripts/post-consumption-example.sh` as a
script which you'd like to run.
```bash
You can pass that script into the consumer container via a host mount:
```yaml
...
consumer:
webserver:
...
volumes:
...
- /home/paperless-ngx/scripts:/path/in/container/scripts/
- /home/paperless-ngx/scripts:/path/in/container/scripts/ # (1)!
environment: # (3)!
...
PAPERLESS_POST_CONSUME_SCRIPT: /path/in/container/scripts/post-consumption-example.sh # (2)!
...
```
Example (docker-compose.yml):
`- /home/foo/paperless-ngx/scripts:/usr/src/paperless/scripts`
which in turn requires the variable `PAPERLESS_POST_CONSUME_SCRIPT` in
`docker-compose.env` to point to
`/path/in/container/scripts/post-consumption-example.sh`.
Example (docker-compose.env):
`PAPERLESS_POST_CONSUME_SCRIPT=/usr/src/paperless/scripts/post-consumption-example.sh`
1. The external scripts directory is mounted to a location inside the container.
2. The internal location of the script is used to set the script to run
3. This can also be set in `docker-compose.env`
Troubleshooting:
@@ -218,7 +219,7 @@ Troubleshooting:
- Pipe your scripts's output to a log file e.g.
`echo "${DOCUMENT_ID}" | tee --append /usr/src/paperless/scripts/post-consumption-example.log`
## File name handling {#file_name_handling}
## File name handling {#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
@@ -301,7 +302,7 @@ value.
!!! tip
You can affect how empty placeholders are treated by changing the
following setting to [true]{.title-ref}.
following setting to `true`.
```
PAPERLESS_FILENAME_FORMAT_REMOVE_NONE=True
@@ -316,7 +317,7 @@ value.
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
[`document renamer <utilities-renamer>`]().
[`document renamer`](/administration#renamer).
!!! warning
@@ -344,7 +345,7 @@ When as single storage layout is not sufficient for your use case,
storage paths come to the rescue. Storage paths allow you to configure
more precisely where each document is stored in the file system.
- Each storage path is a [PAPERLESS_FILENAME_FORMAT]{.title-ref} and
- Each storage path is a `PAPERLESS_FILENAME_FORMAT` and
follows the rules described above
- Each document is assigned a storage path using the matching
algorithms described above, but can be overwritten at any time
@@ -352,7 +353,7 @@ more precisely where each document is stored in the file system.
For example, you could define the following two storage paths:
1. Normal communications are put into a folder structure sorted by
[year/correspondent]{.title-ref}
`year/correspondent`
2. Communications with insurance companies are stored in a flat
structure with longer file names, but containing the full date of
the correspondence.
@@ -363,7 +364,7 @@ Insurances = Insurances/{correspondent}/{created_year}-{created_month}-{created_
```
If you then map these storage paths to the documents, you might get the
following result. For simplicity, [By Year]{.title-ref} defines the same
following result. For simplicity, `By Year` defines the same
structure as in the previous example above.
```text
@@ -384,7 +385,7 @@ structure as in the previous example above.
!!! tip
Defining a storage path is optional. If no storage path is defined for a
document, the global [PAPERLESS_FILENAME_FORMAT]{.title-ref} is applied.
document, the global `PAPERLESS_FILENAME_FORMAT` is applied.
!!! warning
@@ -403,33 +404,38 @@ queued and completed tasks, timing and more. Flower can also be used
with Prometheus, as it exports metrics. For details on its capabilities,
refer to the Flower documentation.
To configure Flower further, create a [flowerconfig.py]{.title-ref} and
place it into the [src/paperless]{.title-ref} directory. For a Docker
To configure Flower further, create a `flowerconfig.py` and
place it into the `src/paperless` directory. For a Docker
installation, you can use volumes to accomplish this:
```yaml
services:
# ...
webserver:
ports:
- 5555:5555 # (2)!
# ...
volumes:
- /path/to/my/flowerconfig.py:/usr/src/paperless/src/paperless/flowerconfig.py:ro
- /path/to/my/flowerconfig.py:/usr/src/paperless/src/paperless/flowerconfig.py:ro # (1)!
```
1. Note the `:ro` tag means the file will be mounted as read only.
2. `flower` runs by default on port 5555, but this can be configured
## Custom Container Initialization
The Docker image includes the ability to run custom user scripts during
startup. This could be utilized for installing additional tools or
Python packages, for example.
Python packages, for example. Scripts are expected to be shell scripts.
To utilize this, mount a folder containing your scripts to the custom
initialization directory, [/custom-cont-init.d]{.title-ref} and place
initialization directory, `/custom-cont-init.d` and place
scripts you wish to run inside. For security, the folder must be owned
by `root` and should have permissions of `a=rx`. Additionally, scripts
must only be writable by `root`.
Your scripts will be run directly before the webserver completes
startup. Scripts will be run by the [root]{.title-ref} user.
startup. Scripts will be run by the `root` user.
If you would like to switch users, the utility `gosu` is available and
preferred over `sudo`.
@@ -445,9 +451,11 @@ services:
webserver:
# ...
volumes:
- /path/to/my/scripts:/custom-cont-init.d:ro
- /path/to/my/scripts:/custom-cont-init.d:ro # (1)!
```
1. Note the `:ro` tag means the folder will be mounted as read only. This is for extra security against changes
## MySQL Caveats {#mysql-caveats}
### Case Sensitivity