Merge branch 'dev' into dev

2024-02-05 09:32:30 -08:00
parent 0cc773f941 c7e0c32226
commit 3c86ad5140
79 changed files with 3967 additions and 3396 deletions
--- a/docs/advanced_usage.md
+++ b/docs/advanced_usage.md
@@ -517,6 +517,18 @@ existing tables) with:
    an older system may fix issues that can arise while setting up Paperless-ngx but
    `utf8mb3` can cause issues with consumption (where `utf8mb4` does not).

+### Missing timezones
+
+MySQL as well as MariaDB do not have any timezone information by default (though some
+docker images such as the official MariaDB image take care of this for you) which will
+cause unexpected behavior with date-based queries.
+
+To fix this, execute one of the following commands:
+
+MySQL: `mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql -p`
+
+MariaDB: `mariadb-tzinfo-to-sql /usr/share/zoneinfo | mariadb -u root mysql -p`
+
 ## Barcodes {#barcodes}

 Paperless is able to utilize barcodes for automatically performing some tasks.
--- a/docs/api.md
+++ b/docs/api.md
@@ -139,7 +139,7 @@ document. Paperless only reports PDF metadata at this point.

 ## Authorization

-The REST api provides three different forms of authentication.
+The REST api provides four different forms of authentication.

 1.  Basic authentication

@@ -177,6 +177,12 @@ The REST api provides three different forms of authentication.

    Tokens can also be managed in the Django admin.

+4.  Remote User authentication
+
+    If enabled (see
+    [configuration](configuration.md#PAPERLESS_ENABLE_HTTP_REMOTE_USER_API)),
+    you can authenticate against the API using Remote User auth.
+
 ## Searching for documents

 Full text searching is available on the `/api/documents/` endpoint. Two
@@ -185,7 +191,7 @@ results:

 - `/api/documents/?query=your%20search%20query`: Search for a document
  using a full text query. For details on the syntax, see [Basic Usage - Searching](usage.md#basic-usage_searching).
- `/api/documents/?more_like=1234`: Search for documents similar to
+- `/api/documents/?more_like_id=1234`: Search for documents similar to
  the document with id 1234.

 Pagination works exactly the same as it does for normal requests on this
@@ -324,6 +330,64 @@ granted). You can pass the parameter `full_perms=true` to API calls to view the
 full permissions of objects in a format that mirrors the `set_permissions`
 parameter above.

+## Bulk Editing
+
+The API supports various bulk-editing operations which are executed asynchronously.
+
+### Documents
+
+For bulk operations on documents, use the endpoint `/api/bulk_edit/` which accepts
+a json payload of the format:
+
+```json
+{
+  "documents": [LIST_OF_DOCUMENT_IDS],
+  "method": METHOD, // see below
+  "parameters": args // see below
+}
+```
+
+The following methods are supported:
+
+- `set_correspondent`
+  - Requires `parameters`: `{ "correspondent": CORRESPONDENT_ID }`
+- `set_document_type`
+  - Requires `parameters`: `{ "document_type": DOCUMENT_TYPE_ID }`
+- `set_storage_path`
+  - Requires `parameters`: `{ "storage_path": STORAGE_PATH_ID }`
+- `add_tag`
+  - Requires `parameters`: `{ "tag": TAG_ID }`
+- `remove_tag`
+  - Requires `parameters`: `{ "tag": TAG_ID }`
+- `modify_tags`
+  - Requires `parameters`: `{ "add_tags": [LIST_OF_TAG_IDS] }` and / or `{ "remove_tags": [LIST_OF_TAG_IDS] }`
+- `delete`
+  - No `parameters` required
+- `redo_ocr`
+  - No `parameters` required
+- `set_permissions`
+  - Requires `parameters`:
+    - `"permissions": PERMISSIONS_OBJ` (see format [above](#permissions)) and / or
+    - `"owner": OWNER_ID or null`
+    - `"merge": true or false` (defaults to false)
+  - The `merge` flag determines if the supplied permissions will overwrite all existing permissions (including
+    removing them) or be merged with existing permissions.
+
+### Objects
+
+Bulk editing for objects (tags, document types etc.) currently supports only updating permissions, using
+the endpoint: `/api/bulk_edit_object_perms/` which requires a json payload of the format:
+
+```json
+{
+  "objects": [LIST_OF_OBJECT_IDS],
+  "object_type": "tags", "correspondents", "document_types" or "storage_paths"
+  "owner": OWNER_ID // optional
+  "permissions": { "view": { "users": [] ... }, "change": { ... } }, // (see 'set_permissions' format above)
+  "merge": true / false // defaults to false, see above
+}
+```
+
 ## API Versioning

 The REST API is versioned since Paperless-ngx 1.3.0.
@@ -380,3 +444,13 @@ Initial API version.
  color to use for a specific tag, which is either black or white
  depending on the brightness of `Tag.color`.
 - Removed field `Tag.colour`.
+
+#### Version 3
+
+- Permissions endpoints have been added.
+- The format of the `/api/ui_settings/` has changed.
+
+#### Version 4
+
+- Consumption templates were refactored to workflows and API endpoints
+  changed as such.
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,5 +1,15 @@
 # Changelog

+## paperless-ngx 2.4.3
+
+### Bug Fixes
+
+- Fix: Ensure the scratch directory exists before consuming via the folder [@stumpylog](https://github.com/stumpylog) ([#5579](https://github.com/paperless-ngx/paperless-ngx/pull/5579))
+
+### All App Changes
+
+- Fix: Ensure the scratch directory exists before consuming via the folder [@stumpylog](https://github.com/stumpylog) ([#5579](https://github.com/paperless-ngx/paperless-ngx/pull/5579))
+
 ## paperless-ngx 2.4.2

 ### Bug Fixes
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -34,6 +34,8 @@ matcher.
        `redis://<username>:<password>@<host>:<port>`
    -   With the requirepass option PAPERLESS_REDIS =
        `redis://:<password>@<host>:<port>`
+    -   To include the redis database index PAPERLESS_REDIS =
+        `redis://<username>:<password>@<host>:<port>/<DBIndex>`

    [More information on securing your Redis
    Instance](https://redis.io/docs/getting-started/#securing-redis).
@@ -462,9 +464,21 @@ applications.

    Defaults to "false" which disables this feature.

+#### [`PAPERLESS_ENABLE_HTTP_REMOTE_USER_API=<bool>`](#PAPERLESS_ENABLE_HTTP_REMOTE_USER_API) {#PAPERLESS_ENABLE_HTTP_REMOTE_USER_API}
+
+: Allows authentication via HTTP_REMOTE_USER directly against the API
+
+    !!! warning
+
+        See the warning above about securing your installation when using remote user header authentication. This setting is separate from
+        `PAPERLESS_ENABLE_HTTP_REMOTE_USER` to avoid introducing a security vulnerability to existing reverse proxy setups. As above,
+        ensure that your reverse proxy does not simply pass the `Remote-User` header from the internet to paperless.
+
+    Defaults to "false" which disables this feature.
+
 #### [`PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME=<str>`](#PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME) {#PAPERLESS_HTTP_REMOTE_USER_HEADER_NAME}

-: If "PAPERLESS_ENABLE_HTTP_REMOTE_USER" is enabled, this
+: If "PAPERLESS_ENABLE_HTTP_REMOTE_USER" or `PAPERLESS_ENABLE_HTTP_REMOTE_USER_API` are enabled, this
 property allows to customize the name of the HTTP header from which
 the authenticated username is extracted. Values are in terms of
 [HttpRequest.META](https://docs.djangoproject.com/en/4.1/ref/request-response/#django.http.HttpRequest.META).
@@ -1378,6 +1392,12 @@ started by the container.

    You can read more about this in the [advanced documentation](advanced_usage.md#celery-monitoring).

+#### [`PAPERLESS_SUPERVISORD_WORKING_DIR=<defined>`](#PAPERLESS_SUPERVISORD_WORKING_DIR) {#PAPERLESS_SUPERVISORD_WORKING_DIR}
+
+: If this environment variable is defined, the `supervisord.log` and `supervisord.pid` file will be created under the specified path in `PAPERLESS_SUPERVISORD_WORKING_DIR`. Setting `PAPERLESS_SUPERVISORD_WORKING_DIR=/tmp` and `PYTHONPYCACHEPREFIX=/tmp/pycache` would allow paperless to work on a read-only filesystem.
+
+    Please take note that the `PAPERLESS_DATA_DIR` and `PAPERLESS_MEDIA_ROOT` paths still have to be writable, just like the `PAPERLESS_SUPERVISORD_WORKING_DIR`. The can be archived by using bind or volume mounts. Only works in the container is run as user *paperless*
+
 ## Frontend Settings

 #### [`PAPERLESS_APP_TITLE=<bool>`](#PAPERLESS_APP_TITLE) {#PAPERLESS_APP_TITLE}
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,6 +6,14 @@
 physical documents into a searchable online archive so you can keep, well, _less paper_.

 [Get started](setup.md){ .md-button .md-button--primary .index-callout }
+[Demo](https://demo.paperless-ngx.com){ .md-button .md-button--secondary target=\_blank }
+
+<div style="display: flex; justify-content: end; margin-top: -1.5rem;">
+  <a href="https://m.do.co/c/8d70b916d462" target="_blank">
+    <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_white.svg#only-dark" class="no-lightbox" width="150px">
+    <img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_black.svg#only-light" class="no-lightbox" width="150px">
+  </a>
+</div>

 </div>
 <div class="grid-right" markdown>