- Additional features
- Large changes to many distinct files
-- Breaking or depreciation of existing features
+- Breaking or deprecation of existing features
Our community review process for `non-trivial` PRs is the following:
After that, [make a backup](#backup).
-1. If you pull the image from the docker hub, all you need to do is:
+1. If you pull the image from the docker hub, all you need to do is:
- ```shell-session
- $ docker-compose pull
- $ docker-compose up
- ```
+ ```shell-session
+ $ docker-compose pull
+ $ docker-compose up
+ ```
- The docker-compose files refer to the `latest` version, which is
- always the latest stable release.
+ The docker-compose files refer to the `latest` version, which is
+ always the latest stable release.
-2. If you built the image yourself, do the following:
+1. If you built the image yourself, do the following:
- ```shell-session
- $ git pull
- $ docker-compose build
- $ docker-compose up
- ```
+ ```shell-session
+ $ git pull
+ $ docker-compose build
+ $ docker-compose up
+ ```
Running `docker-compose up` will also apply any new database migrations.
If you see everything working, press CTRL+C once to gracefully stop
- Inaccessible thumbnails due to improper permissions.
- Documents without any content (warning).
- Orphaned files in the media directory (warning). These are files
- that are not referenced by any document im paperless.
+ that are not referenced by any document in paperless.
```
document_sanity_checker
# Advanced Topics
-Paperless offers a couple features that automate certain tasks and make
+Paperless offers a couple of features that automate certain tasks and make
your life easier.
## Matching tags, correspondents, document types, and storage paths {#matching}
(i.e. preserve ordering) in the PDF.
- **Regular expression:** Parses the match as a regular expression and
tries to find a match within the document.
-- **Fuzzy match:** I don't know. Look at the source.
+- **Fuzzy match:** I don't know. Look at [the source](https://github.com/paperless-ngx/paperless-ngx/blob/main/src/documents/matching.py).
- **Auto:** Tries to automatically match new documents. This does not
- require you to set a match. See the notes below.
+ require you to set a match. See the [notes below](#automatic-matching).
When using the _any_ or _all_ matching algorithms, you can search for
terms that consist of multiple words by enclosing them in double quotes.
decide when not to assign a certain tag, correspondent, document
type, or storage path. This will usually be the case as you start
filling up paperless with documents. Example: If all your documents
- are either from "Webshop" and "Bank", paperless will assign one
+ are either from "Webshop" or "Bank", paperless will assign one
of these correspondents to ANY new document, if both are set to
automatic matching.
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
lets you execute scripts of your own choosing just before or after a
-document is consumed using a couple simple hooks.
+document is consumed using a couple of simple hooks.
Just write a script, put it somewhere that Paperless can read & execute,
and then put the path to that script in `paperless.conf` or
!!! warning
The post consumption script should not modify the document files
- directly
+ directly.
The script's stdout and stderr will be logged line by line to the
webserver log, along with the exit code of the script.
`PAPERLESS_OCR_MODE=<mode>`
-: Tell paperless when and how to perform ocr on your documents. Four
+: Tell paperless when and how to perform ocr on your documents. Three
modes are available:
- `skip`: Paperless skips all pages and will perform ocr only on
creative with their installation, you probably won't need to edit any
of these. However, if you've installed these programs somewhere where
simply typing the name of the program doesn't automatically execute it
-(ie. the program isn't in your \$PATH), then you'll need to specify
+(ie. the program isn't in your $PATH), then you'll need to specify
the literal path for that program.
`PAPERLESS_CONVERT_BINARY=<path>`
with English, German, Italian, Spanish and French. If your language
is not in this list, install additional languages with this
configuration option. You will need to [find the right LangCodes](https://tesseract-ocr.github.io/tessdoc/Data-Files-in-different-versions.html)
-but note that (tesseract-ocr-\* package names)[https://packages.debian.org/bullseye/graphics/]
+but note that [tesseract-ocr-\* package names](https://packages.debian.org/bullseye/graphics/)
do not always correspond with the language codes e.g. "chi_tra" should be
specified as "chi-tra".
!!! note
- Every command is executed directly from the root folder of the project unless specified otherwise.
+ Every command is executed directly from the root folder of the project unless specified otherwise.
1. Install prerequisites + pipenv as mentioned in
[Bare metal route](/setup#bare_metal).
The following commands are all performed in the `src-ui`-directory. You will need a running back end (including an active session) to connect to the back end API. To spin it up refer to the commands under the section [above](#back-end-development).
-1. Install the Angular CLI. You might need sudo privileges
- to perform this command:
+1. Install the Angular CLI. You might need sudo privileges to perform this command:
- ```bash
- $ npm install -g @angular/cli
- ```
+ ```bash
+ $ npm install -g @angular/cli
+ ```
-2. Make sure that it's on your path.
+2. Make sure that it's on your path.
-3. Install all necessary modules:
+3. Install all necessary modules:
- ```bash
- $ npm install
- ```
+ ```bash
+ $ npm install
+ ```
-4. You can launch a development server by running:
+4. You can launch a development server by running:
- ```bash
- $ ng serve
- ```
+ ```bash
+ $ ng serve
+ ```
- This will automatically update whenever you save. However, in-place
- compilation might fail on syntax errors, in which case you need to
- restart it.
+ This will automatically update whenever you save. However, in-place
+ compilation might fail on syntax errors, in which case you need to
+ restart it.
- By default, the development server is available on `http://localhost:4200/` and is configured to access the API at
- `http://localhost:8000/api/`, which is the default of the backend. If you enabled `DEBUG` on the back end, several security overrides for allowed hosts, CORS and X-Frame-Options are in place so that the front end behaves exactly as in production.
+ By default, the development server is available on `http://localhost:4200/` and is configured to access the API at
+ `http://localhost:8000/api/`, which is the default of the backend. If you enabled `DEBUG` on the back end, several security overrides for allowed hosts, CORS and X-Frame-Options are in place so that the front end behaves exactly as in production.
### Testing and code style
-- The front end code (.ts, .html, .scss) use `prettier` for code
- formatting via the Git `pre-commit` hooks which run automatically on
- commit. See [above](#code-formatting-with-pre-commit-hooks) for installation instructions. You can also run this via the CLI with a
- command such as
+The front end code (.ts, .html, .scss) use `prettier` for code
+formatting via the Git `pre-commit` hooks which run automatically on
+commit. See [above](#code-formatting-with-pre-commit-hooks) for installation instructions. You can also run this via the CLI with a
+command such as
+
+```bash
+$ git ls-files -- '*.ts' | xargs pre-commit run prettier --files
+```
- ```bash
- $ git ls-files -- '*.ts' | xargs pre-commit run prettier --files
- ```
+Front end testing uses Jest and Playwright. Unit tests and e2e tests,
+respectively, can be run non-interactively with:
-- Front end testing uses Jest and Playwright. Unit tests and e2e tests,
- respectively, can be run non-interactively with:
+```bash
+$ ng test
+$ npx playwright test
+```
- ```bash
- $ ng test
- $ npx playwright test
- ```
+Playwright also includes a UI which can be run with:
- - Playwright also includes a UI which can be run with:
+```bash
+$ npx playwright test --ui
+```
- ```bash
- $ npx playwright test --ui
- ```
+### Building the frontend
-- In order to build the front end and serve it as part of Django, execute:
+In order to build the front end and serve it as part of Django, execute:
- ```bash
- $ ng build --configuration production
- ```
+```bash
+$ ng build --configuration production
+```
- This will build the front end and put it in a location from which the
- Django server will serve it as static content. This way, you can verify
- that authentication is working.
+This will build the front end and put it in a location from which the
+Django server will serve it as static content. This way, you can verify
+that authentication is working.
## Localization
## _What's the general plan for Paperless-ngx?_
**A:** While Paperless-ngx is already considered largely
-"feature-complete" it is a community-driven project and development
-will be guided in this way. New features can be submitted via GitHub
-discussions and "up-voted" by the community but this is not a
-guarantee the feature will be implemented. This project will always be
+"feature-complete", it is a community-driven project and development
+will be guided in this way. New features can be submitted via
+[GitHub discussions](https://github.com/paperless-ngx/paperless-ngx/discussions)
+and "up-voted" by the community, but this is not a
+guarantee that the feature will be implemented. This project will always be
open to collaboration in the form of PRs, ideas etc.
## _I'm using docker. Where are my documents?_
WebP images are processed with OCR and converted into PDF documents.
- Plain text documents are supported as well and are added verbatim to
paperless.
-- With the optional Tika integration enabled (see [Tika configuration](/configuration#tika),
+- With the optional Tika integration enabled (see [Tika configuration](https://docs.paperless-ngx.com/configuration#tika)),
Paperless also supports various Office documents (.docx, .doc, odt,
.ppt, .pptx, .odp, .xls, .xlsx, .ods).
## _How do I install paperless-ngx on Raspberry Pi?_
**A:** Docker images are available for armv7 and arm64 hardware, so just
-follow the docker-compose instructions. Apart from more required disk
+follow the [docker-compose instructions](https://docs.paperless-ngx.com/setup/#installation). Apart from more required disk
space compared to a bare metal installation, docker comes with close to
zero overhead, even on Raspberry Pi.
projects / thirdparty / paperless-ngx.git / commitdiff
