paradizelost/paperless-ngx
1
0
Fork 0
mirror of https://github.com/paperless-ngx/paperless-ngx.git synced 2025-07-28 18:24:38 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'dev'

Browse Source
This commit is contained in:
shamoon
2025-01-13 07:47:08 -08:00
parent d77c9e3bd5 5c1039d07d
commit 5821033e3d
522 changed files with 120433 additions and 81506 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/administration.md
View File

@@ -81,8 +81,8 @@ $ docker compose down
1. If you pull the image from the docker hub, all you need to do is:
```shell-session
$ docker compose pull
$ docker compose up
docker compose pull
docker compose up
```
The Docker Compose files refer to the `latest` version, which is
@@ -91,9 +91,9 @@ $ docker compose down
1. If you built the image yourself, do the following:
```shell-session
$ git pull
$ docker compose build
$ docker compose up
git pull
docker compose build
docker compose up
```
Running `docker compose up` will also apply any new database migrations.
@@ -155,7 +155,7 @@ following:
environment before that, if you use one.
```shell-session
$ pip install -r requirements.txt
pip install -r requirements.txt
```
!!! note
@@ -168,8 +168,8 @@ following:
3. Migrate the database.
```shell-session
$ cd src
$ python3 manage.py migrate # (1)
cd src
python3 manage.py migrate # (1)
```
1. Including `sudo -Hu <paperless_user>` may be required
@@ -241,6 +241,7 @@ document_exporter target [-c] [-d] [-f] [-na] [-nt] [-p] [-sm] [-z]
optional arguments:
-c, --compare-checksums
-cj, --compare-json
-d, --delete
-f, --use-filename-format
-na, --no-archive
@@ -269,7 +270,8 @@ only export changed and added files. Paperless determines whether a file
has changed by inspecting the file attributes "date/time modified" and
"size". If that does not work out for you, specify `-c` or
`--compare-checksums` and paperless will attempt to compare file
checksums instead. This is slower.
checksums instead. This is slower. The manifest and metadata json files
are always updated, unless `cj` or `--compare-json` is specified.
Paperless will not remove any existing files in the export directory. If
you want paperless to also remove files that do not belong to the
@@ -622,3 +624,12 @@ document_fuzzy_match [--ratio] [--processes N]
If providing the `--delete` option, it is highly recommended to have a backup.
While every effort has been taken to ensure proper operation, there is always the
chance of deletion of a file you want to keep.
### Prune history (audit log) entries {#prune-history}
If the audit log is enabled Paperless-ngx keeps an audit log of all changes made to documents. Functionality to automatically remove entries for deleted documents was added but
entries created prior to this are not removed. This command allows you to prune the audit log of entries that are no longer needed.
```shell
prune_audit_logs
```

17
docs/api.md
View File

@@ -365,6 +365,10 @@ The endpoint supports the following optional form fields:
- `custom_fields`: An array of custom field ids to assign (with an empty
value) to the document.
!!! note
Sending a `Content-Length` header with correct size is mandatory.
The endpoint will immediately return HTTP 200 if the document consumption
process was started successfully, with the UUID of the consumption task
as the data. No additional status information about the consumption process
@@ -473,6 +477,11 @@ The following methods are supported:
- Requires `parameters`:
- `"pages": [..]` The list should be a list of integers e.g. `"[2,3,4]"`
- The delete_pages operation only accepts a single document.
- `modify_custom_fields`
- Requires `parameters`:
- `"add_custom_fields": { CUSTOM_FIELD_ID: VALUE }`: JSON object consisting of custom field id:value pairs to add to the document, can also be a list of custom field IDs
to add with empty values.
- `"remove_custom_fields": [CUSTOM_FIELD_ID]`: custom field ids to remove from the document.
### Objects
@@ -556,3 +565,11 @@ Initial API version.
- Consumption templates were refactored to workflows and API endpoints
changed as such.
#### Version 5
- Added bulk deletion methods for documents and objects.
#### Version 6
- Moved acknowledge tasks endpoint to be under `/api/tasks/acknowledge/`.

6
docs/configuration.md
View File

@@ -596,7 +596,7 @@ system. See the corresponding
: Disables the regular frontend username / password login, i.e. once you have setup SSO. Note that this setting does not disable the Django admin login nor logging in with local credentials via the API. To prevent access to the Django admin, consider blocking `/admin/` in your [web server or reverse proxy configuration](https://github.com/paperless-ngx/paperless-ngx/wiki/Using-a-Reverse-Proxy-with-Paperless-ngx).
You can optionally also automatically redirect users to the SSO login with [PAPERLESS_REDIRECT_LOGIN_TO_SSO](#PAPERLESS_REDIRECT_LOGIN_TO_SSO)
You can optionally also automatically redirect users to the SSO login with [PAPERLESS_REDIRECT_LOGIN_TO_SSO](#PAPERLESS_REDIRECT_LOGIN_TO_SSO)
Defaults to False
@@ -1523,7 +1523,7 @@ one pod).
actual user ID on the host system, which you can get by executing
``` shell-session
$ id -u
id -u
```
Paperless will change ownership on its folders to this user, so you
@@ -1538,7 +1538,7 @@ actual user ID on the host system, which you can get by executing
actual group ID on the host system, which you can get by executing
``` shell-session
$ id -g
id -g
```
Paperless will change ownership on its folders to this group, so you

47
docs/development.md
View File

@@ -69,13 +69,13 @@ first-time setup.
3. Create `consume` and `media` directories:
```bash
$ mkdir -p consume media
mkdir -p consume media
```
4. Install the Python dependencies:
```bash
$ pipenv install --dev
pipenv install --dev
```
!!! note
@@ -85,7 +85,7 @@ first-time setup.
5. Install pre-commit hooks:
```bash
$ pre-commit install
pre-commit install
```
6. Apply migrations and create a superuser for your development instance:
@@ -93,8 +93,8 @@ first-time setup.
```bash
# src/
$ python3 manage.py migrate
$ python3 manage.py createsuperuser
python3 manage.py migrate
python3 manage.py createsuperuser
```
7. You can now either ...
@@ -108,7 +108,7 @@ first-time setup.
- spin up a bare redis container
```
$ docker run -d -p 6379:6379 --restart unless-stopped redis:latest
docker run -d -p 6379:6379 --restart unless-stopped redis:latest
```
8. Continue with either back-end or front-end development – or both :-).
@@ -176,7 +176,7 @@ The front end is built using AngularJS. In order to get started, you need Node.j
1. Install the Angular CLI. You might need sudo privileges to perform this command:
```bash
$ npm install -g @angular/cli
npm install -g @angular/cli
```
2. Make sure that it's on your path.
@@ -184,13 +184,13 @@ The front end is built using AngularJS. In order to get started, you need Node.j
3. Install all necessary modules:
```bash
$ npm install
npm install
```
4. You can launch a development server by running:
```bash
$ ng serve
ng serve
```
This will automatically update whenever you save. However, in-place
@@ -335,13 +335,13 @@ If you want to build the documentation locally, this is how you do it:
1. Have an active pipenv shell (`pipenv shell`) and install Python dependencies:
```bash
$ pipenv install --dev
pipenv install --dev
```
2. Build the documentation
```bash
$ mkdocs build --config-file mkdocs.yml
mkdocs build --config-file mkdocs.yml
```
_alternatively..._
@@ -352,7 +352,7 @@ If you want to build the documentation locally, this is how you do it:
something.
```bash
$ mkdocs serve
mkdocs serve
```
## Building the Docker image
@@ -450,3 +450,26 @@ def myparser_consumer_declaration(sender, **kwargs):
mime types have many extensions associated with them and the Python
methods responsible for guessing the extension do not always return
the same value.
## Using Visual Studio Code devcontainer
Another easy way to get started with development is to use Visual Studio
Code devcontainers. This approach will create a preconfigured development
environment with all of the required tools and dependencies.
[Learn more about devcontainers](https://code.visualstudio.com/docs/devcontainers/containers).
The .devcontainer/vscode/tasks.json and .devcontainer/vscode/launch.json files
contain more information about the specific tasks and launch configurations (see the
non-standard "description" field).
To get started:
1. Clone the repository on your machine and open the Paperless-ngx folder in VS Code.
2. VS Code will prompt you with "Reopen in container". Do so and wait for the environment to start.
3. Initialize the project by running the task **Project Setup: Run all Init Tasks**. This
will initialize the database tables and create a superuser. Then you can compile the front end
for production or run the frontend in debug mode.
4. The project is ready for debugging, start either run the fullstack debug or individual debug
processes. Yo spin up the project without debugging run the task **Project Start: Run all Services**

18
docs/setup.md
View File

@@ -30,7 +30,7 @@ account. The script essentially automatically performs the steps described in [D
2. Download and run the installation script:
```shell-session
$ bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
```
!!! note
@@ -135,13 +135,13 @@ account. The script essentially automatically performs the steps described in [D
execute the following command:
```shell-session
$ docker compose run --rm webserver createsuperuser
docker compose run --rm webserver createsuperuser
```
or using docker exec from within the container:
```shell-session
$ python3 manage.py createsuperuser
python3 manage.py createsuperuser
```
This will guide you through the superuser setup.
@@ -188,7 +188,7 @@ account. The script essentially automatically performs the steps described in [D
`docker compose pull` to pull the image, run
```shell-session
$ docker compose build
docker compose build
```
instead to build the image.
@@ -557,8 +557,8 @@ Migration to paperless-ngx is then performed in a few simple steps:
1. Stop paperless.
```bash
$ cd /path/to/current/paperless
$ docker compose down
cd /path/to/current/paperless
docker compose down
```
2. Do a backup for two purposes: If something goes wrong, you still
@@ -582,7 +582,7 @@ Migration to paperless-ngx is then performed in a few simple steps:
names of your volumes with
``` shell-session
$ docker volume ls | grep _data
docker volume ls | grep _data
```
and adjust the project name in the `.env` file so that it matches
@@ -603,7 +603,7 @@ Migration to paperless-ngx is then performed in a few simple steps:
the search index:
```shell-session
$ docker compose run --rm webserver document_index reindex
docker compose run --rm webserver document_index reindex
```
This will migrate your database and create the search index. After
@@ -612,7 +612,7 @@ Migration to paperless-ngx is then performed in a few simple steps:
8. Start paperless-ngx.
```bash
$ docker compose up -d
docker compose up -d
```
This will run paperless in the background and automatically start it

2
docs/troubleshooting.md
View File

@@ -18,7 +18,7 @@ Check for the following issues:
automatically. Manually invoke the task processor by executing
```shell-session
$ celery --app paperless worker
celery --app paperless worker
```
- Look at the output of paperless and inspect it for any errors.

58
docs/usage.md
View File

@@ -299,6 +299,12 @@ In order to enable the password reset feature you will need to setup an SMTP bac
[`PAPERLESS_EMAIL_HOST`](configuration.md#PAPERLESS_EMAIL_HOST). If your installation does not have
[`PAPERLESS_URL`](configuration.md#PAPERLESS_URL) set, the reset link included in emails will use the server host.
### Two-factor authentication
Users can enable two-factor authentication (2FA) for their accounts from the 'My Profile' dialog. Opening the dropdown reveals a QR code that can be scanned by a 2FA app (e.g. Google Authenticator) to generate a code. The code must then be entered in the dialog to enable 2FA. If the code is accepted and 2FA is enabled, the user will be shown a set of 10 recovery codes that can be used to login in the event that the 2FA device is lost or unavailable. These codes should be stored securely and cannot be retrieved again. Once enabled, users will be required to enter a code from their 2FA app when logging in.
Should a user lose access to their 2FA device and all recovery codes, a superuser can disable 2FA for the user from the 'Users & Groups' management screen.
## Workflows
!!! note
@@ -316,6 +322,8 @@ fields and permissions, which will be merged.
### Workflow Triggers
#### Types
Currently, there are three events that correspond to workflow trigger 'types':
1. **Consumption Started**: _before_ a document is consumed, so events can include filters by source (mail, consumption
@@ -325,8 +333,10 @@ Currently, there are three events that correspond to workflow trigger 'types':
be used for filtering.
3. **Document Updated**: when a document is updated. Similar to 'added' events, triggers can include filtering by content matching,
tags, doc type, or correspondent.
4. **Scheduled**: a scheduled trigger that can be used to run workflows at a specific time. The date used can be either the document
added, created, updated date or you can specify a (date) custom field. You can also specify a day offset from the date.
The following flow diagram illustrates the three trigger types:
The following flow diagram illustrates the three document trigger types:
```mermaid
flowchart TD
@@ -372,25 +382,49 @@ Workflows allow you to filter by:
### Workflow Actions
There are currently two types of workflow actions, "Assignment", which can assign:
#### Types
- Title, see [title placeholders](usage.md#title-placeholders) below
The following workflow action types are available:
##### Assignment
"Assignment" actions can assign:
- Title, see [workflow placeholders](usage.md#workflow-placeholders) below
- Tags, correspondent, document type and storage path
- Document owner
- View and / or edit permissions to users or groups
- Custom fields. Note that no value for the field will be set
and "Removal" actions, which can remove either all of or specific sets of the following:
##### Removal
"Removal" actions can remove either all of or specific sets of the following:
- Tags, correspondents, document types or storage paths
- Document owner
- View and / or edit permissions
- Custom fields
#### Title placeholders
##### Email
Workflow titles can include placeholders but the available options differ depending on the type of
workflow trigger. This is because at the time of consumption (when the title is to be set), no automatic tags etc. have been
"Email" actions can send documents via email. This action requires a mail server to be [configured](configuration.md#email-sending). You can specify:
- The recipient email address(es) separated by commas
- The subject and body of the email, which can include placeholders, see [placeholders](usage.md#workflow-placeholders) below
- Whether to include the document as an attachment
##### Webhook
"Webhook" actions send a POST request to a specified URL. You can specify:
- The URL to send the request to
- The request body as text or as key-value pairs, which can include placeholders, see [placeholders](usage.md#workflow-placeholders) below.
- The request headers as key-value pairs
#### Workflow placeholders
Some workflow text can include placeholders but the available options differ depending on the type of
workflow trigger. This is because at the time of consumption (when the text is to be set), no automatic tags etc. have been
applied. You can use the following placeholders with any trigger type:
- `{correspondent}`: assigned correspondent name
@@ -405,6 +439,7 @@ applied. You can use the following placeholders with any trigger type:
- `{added_day}`: added day
- `{added_time}`: added time in HH:MM format
- `{original_filename}`: original file name without extension
- `{filename}`: current file name without extension
The following placeholders are only available for "added" or "updated" triggers
@@ -416,6 +451,7 @@ The following placeholders are only available for "added" or "updated" triggers
- `{created_month_name_short}`: created month short name
- `{created_day}`: created day
- `{created_time}`: created time in HH:MM format
- `{doc_url}`: URL to the document in the web UI. Requires the `PAPERLESS_URL` setting to be set.
### Workflow permissions
@@ -752,8 +788,8 @@ Paperless-ngx consists of the following components:
with paperless. You may start the webserver directly with
```shell-session
$ cd /path/to/paperless/src/
$ gunicorn -c ../gunicorn.conf.py paperless.wsgi
cd /path/to/paperless/src/
gunicorn -c ../gunicorn.conf.py paperless.wsgi
```
or by any other means such as Apache `mod_wsgi`.
@@ -768,8 +804,8 @@ Paperless-ngx consists of the following components:
Start the consumer with the management command `document_consumer`:
```shell-session
$ cd /path/to/paperless/src/
$ python3 manage.py document_consumer
cd /path/to/paperless/src/
python3 manage.py document_consumer
```
- **The task processor:** Paperless relies on [Celery - Distributed