From ea614c22a7e2ad558c29ab0eb5c88276081f52c6 Mon Sep 17 00:00:00 2001 From: eikek Date: Wed, 16 Jun 2021 23:57:58 +0200 Subject: [PATCH] Documentation updates/fixes --- website/site/content/docs/configure/_index.md | 14 ++- website/site/content/docs/install/docker.md | 17 ++- .../site/content/docs/install/downgrading.md | 44 ++----- website/site/content/docs/install/nix.md | 1 - .../site/content/docs/install/reverseproxy.md | 17 ++- website/site/content/docs/install/rpi.md | 7 +- website/site/content/docs/intro/_index.md | 112 ------------------ website/site/content/docs/query/_index.md | 15 ++- website/site/content/docs/tools/consumedir.md | 23 +++- website/site/templates/footer.html | 4 +- 10 files changed, 77 insertions(+), 177 deletions(-) diff --git a/website/site/content/docs/configure/_index.md b/website/site/content/docs/configure/_index.md index 6629a0c1..4a8f14ea 100644 --- a/website/site/content/docs/configure/_index.md +++ b/website/site/content/docs/configure/_index.md @@ -173,7 +173,8 @@ When installing docspell manually, just install solr and create a core as described in the [solr documentation](https://solr.apache.org/guide/8_4/installing-solr.html). That will provide you with the connection url (the last part is the -core name). +core name). If Docspell detects an empty core it will run a schema +setup on start automatically. The `full-text-search.solr` options are the same for joex and the restserver. @@ -238,7 +239,7 @@ absolute urls and to configure the authenication cookie. By default it is build using the information from the `bind` setting, which is `http://localhost:7880`. -If the default is not changed, docspell will use the login request to +If the default is not changed, docspell will use the request to determine the base-url. It first inspects the `X-Forwarded-For` header that is often used with reverse proxies. If that is not present, the `Host` header of the request is used. However, if the `base-url` @@ -249,6 +250,8 @@ docspell.server.base-url = ... docspell.joex.base-url = ... ``` +If you are unsure, leave it at its default. + ### Examples ``` @@ -262,7 +265,8 @@ docspell.joex.baseurl = "http://192.168.101.10" The `app-id` is the identifier of the corresponding instance. It *must be unique* for all instances. By default the REST server uses `rest1` and joex `joex1`. It is recommended to overwrite this setting to have -an explicit and stable identifier. +an explicit and stable identifier should multiple instances are +intended. ``` bash docspell.server.app-id = "rest1" @@ -334,9 +338,9 @@ can be given as Base64 encoded string or in hex form. Use the prefix `hex:` and `b64:`, respectively. If no prefix is given, the UTF8 bytes of the string are used. -The `session-valid` deterimens how long a token is valid. This can be +The `session-valid` determines how long a token is valid. This can be just some minutes, the web application obtains new ones -periodically. So a short time is recommended. +periodically. So a rather short time is recommended. ## File Processing diff --git a/website/site/content/docs/install/docker.md b/website/site/content/docs/install/docker.md index db222765..790929a1 100644 --- a/website/site/content/docs/install/docker.md +++ b/website/site/content/docs/install/docker.md @@ -128,18 +128,19 @@ below. There is a [docker-compose](https://docs.docker.com/compose/) setup available in the `/docker/docker-compose` folder. This setup is similiar to the example above, adding fulltext search and a PostgreSQL -database by using just one command. It's only 3 steps to get started: +database by using just one command. It's only a few steps to get +started. ### Start Docspell -#### Get the docker-compose files +#### 1. Get the docker-compose files -Either via cloning the whole repository: +There are two options. You can clone the whole repository: ```bash $ git clone https://github.com/eikek/docspell ``` -This downloads all sources. What you need is only one subdirectory. So +This downloads all sources. What you actually need is only 3 files. So if you don't have git or don't want to clone the whole repo, use these steps instead: @@ -152,7 +153,11 @@ $ wget https://raw.githubusercontent.com/eikek/docspell/master/docker/docker-com ``` You can choose any directory instead of -`docspell/docker/docker-compose`, of course. +`docspell/docker/docker-compose`, of course. It's only this folder to +make the rest of the guide work for both ways of obtaining the +docker-compose file. + +#### 2. Run `docker-compose up` Change into the new `docker-compose` directory, for example: @@ -160,7 +165,7 @@ Change into the new `docker-compose` directory, for example: $ cd docspell/docker/docker-compose ``` -#### Run `docker-compose up` +Then run `docker-compose`: ```bash $ export DOCSPELL_HEADER_VALUE="my-secret-123" diff --git a/website/site/content/docs/install/downgrading.md b/website/site/content/docs/install/downgrading.md index 014bc93b..558fc031 100644 --- a/website/site/content/docs/install/downgrading.md +++ b/website/site/content/docs/install/downgrading.md @@ -3,44 +3,18 @@ title = "Downgrading" weight = 37 +++ +{% infobubble(mode="info", title="⚠ Please note") %} Downgrading is currently not supported! -Note, it is not safe to install a previous version, because the -database will not be compatible. Therefore, it is recommended to take -a backup of the database before upgrading. +It is not safe to install a previous version, because the database +will most likely not be compatible. Therefore, it is recommended to +take a backup of the database before upgrading. +{% end %} + + Should something not work out as expected, you need to restore the backup and then go back to the previous version. -## Docker-Compose - -The default `docker-compose.yml` file points to images using the -`-LATEST` tag. You need to edit this file and replace `-LATEST` with -the concrete version, like `-v0.20.0`. - -Then run the three steps as when upgrading: - -``` bash -$ docker-compose down -$ docker-compose pull -$ docker-compose up --force-recreate --build -d -``` - - -## ZIP / Deb Files - -Simply download a concrete version and re-install it using your -package manager or unpack the zip file. - - -## Nix - -When using the provided nix setup, the `currentPkg` always points to -the latest version. But most other versions are also provided and can -be chosen from: - -``` nix -# … - docspell = callPackage (docspell.pkg docspell.cfg.v0_20_0) {}; -# … -``` +If you need to downgrade after running for a while, create an issue or +meet on matrix/gitter. We should be able to find a way. diff --git a/website/site/content/docs/install/nix.md b/website/site/content/docs/install/nix.md index a9e44ee4..426cfee4 100644 --- a/website/site/content/docs/install/nix.md +++ b/website/site/content/docs/install/nix.md @@ -63,7 +63,6 @@ selecting the most current release. For example it translates to is `{{version()}}`. - ## Upgrading Since [downgrading](@/docs/install/downgrading.md) is not supported, diff --git a/website/site/content/docs/install/reverseproxy.md b/website/site/content/docs/install/reverseproxy.md index 683c13c3..9534aff8 100644 --- a/website/site/content/docs/install/reverseproxy.md +++ b/website/site/content/docs/install/reverseproxy.md @@ -21,6 +21,7 @@ configuration file: to change the `bind.address` setting to be either `0.0.0.0` or the ip address of the network interface that the reverse proxy server connects to. + ``` bash docspell.server { # Where the server binds to. @@ -32,9 +33,10 @@ configuration file: ``` Note that a value of `0.0.0.0` instead of `192.168.1.11` will bind the server to every network interface. -- Docspell needs to know the external url. The `base-url` setting - must point to the external address. Using above values, it must be - set to `https://docspell.example.com`. +- (Optional) Docspell needs to know the external url. The `base-url` + setting should point to the external address. Using above values, it + would be `https://docspell.example.com`. + ``` bash docspell.server { # This is the base URL this application is deployed to. This is used @@ -44,12 +46,15 @@ configuration file: } ``` + You can also leave the default settings (`localhost`), in this case + Docspell uses the request header to determine the external url. + Note that this example assumes that the docspell-joex component is on the same machine. This page is only related for exposing the REST server and web application. -If you have examples for more servers, please let me know or add it to -this site. +If you have examples for more http servers (e.g. apache), please let +me know or add it to this site. # Nginx @@ -90,6 +95,8 @@ server { proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; + + //client_max_body_size 40M; //to allow larger uploads } } ``` diff --git a/website/site/content/docs/install/rpi.md b/website/site/content/docs/install/rpi.md index 4e268515..2c4a3588 100644 --- a/website/site/content/docs/install/rpi.md +++ b/website/site/content/docs/install/rpi.md @@ -3,15 +3,16 @@ title = "Raspberry-Pi and Similiar" weight = 40 +++ -# Raspberry Pi, and similiar - -Both component can run next to each other on a raspberry pi or +Both components can run next to each other on a raspberry pi or similiar device. There is a [project on github](https://github.com/docspell/rpi-scripts) that can help with setting up a raspberry pi with docspell. +The docker images are built for arm64 and armv7, these can also be +used on the pi. + ## REST Server diff --git a/website/site/content/docs/intro/_index.md b/website/site/content/docs/intro/_index.md index cd394997..5d35d3b1 100644 --- a/website/site/content/docs/intro/_index.md +++ b/website/site/content/docs/intro/_index.md @@ -149,115 +149,3 @@ create a folder and associate members. It is possible to put items in these folders and docspell shows only items that are either in no specific folder or in a folder where the current user is owner or member. - -# Rationale - -In 2019, I started to think about creating a dms-like tool that is now -Docspell. It started at the end of that year with the initial version, -including the very basic idea around which I want to create some kind -of document management system. - -The following anecdote summarizes why I thought yet another dms-like -tool might be useful. - -I tried some DMS at that time, to see whether they could help me with -the ever growing pile of documents. It's not just postal mail, now it -gets mixed with invoices via e-mail, bank statements I need to -download at some "portal" etc. It's all getting a huge mess. When -looking for a specific document, it's hard to find. - -I found all the enterprisy DMS are way above of what I need. They are -rather difficult to setup and very hard to explain to non-technical -people. They offer a lot of features and there is quite some time -required to extract what's needed. I then discovered tools, that seem -to better suite my needs. Their design were simple and very close to -what I was looking for, making it a good fit for single user. There -were only a few things to nag: - -1. Often it was not possible to track multiple files as one "unit". - For example: reports with accompanying pictures that I would like - to treat as a single unit. It also more naturally fits to the - common e-mail. -2. Missing good multi-user support; and/or a simple enough interface - so that non-technical users can also make sense of it. -3. Missing some features important to me, like "send this by mail", a - full REST api, and some more -4. still a lot of "manually" organizing documents - -These are not big complaints, they are solvable somehow. I want to -focus on the last point: most systems didn't offer help with -organizing the documents. I didn't find any, that included basic -machine learning features. On most systems it was possible to organize -documents into a custom folder structure. But it was all manually. You -would need to move incoming documents into some subfolder. Some -systems offered rules that get applied to documents in order to put -them into the right place. Many offered tags, too, which relieves some -of weight of this text. But they were also all manual. So the idea -came to let the computer do a little more to help organize documents. - -Let's start with the rules approach: A rule may look like this: - -> when the document contains a text 'invoice' and 'repair company x', -> then put it in subfolder B". - -This rule can be applied to all the new documents to get automatically -placed into this subfolder. I think there are some drawbacks to this -approach: - -- rules may change over time. Then you either must re-apply them all - to all documents or leave older ones where they are. If re-applying - them, some documents may not be in places as before which can easily - confuse coworkers. -- these rules may interfere with each other, then it might get more - difficult to know where a document is -- rules can become complex, be comprised of regular expressions, which - are really only suited to technical people and need to be - maintained. - -I decided to try out a different approach: a "search-only" one¹. -Instead of using a manual created folder structure, I simply search -every time using this rule. In essence such a rule is a search query. -But searching with rules like the one above is not very efficient. One -would need to do fulltext searches, even extracting dates "on the fly" -etc. It wouldn't be very reliable either. That's why documents have -properties (called metadata). In my case most of them have a -correspondent, a date and so on. If these properties were defined on -documents, the queries become quite efficient. The idea is now, not to -use rules for moving documents to some place, but for attaching -properties, information, to each document. This solves a few issues: -they can't get easily out of sync, and they can't interfere. Then -docspell can help with finding some of these properties automatically. -For example: it can propose properties by looking at the text. It can -also take existing documents into account when suggesting tags. In -docspell, it is not possible to define custom rules, instead it tries -to find these rules for you by looking at the text and your previous -documents. - -That said, there is still a manual process involved, but I found it -much lighter. Once in a while, looking at new documents and confirming -or fixing the metadata is necessary. This doesn't involve deciding for -a place, though. What properties you are interested to track can be -configured; should you only need a correspondent and a date, -everything else can be hidden. - -So in docspell, all documents are just in one big pile… but every -document has metadata attached that can be used to quickly find what -you need. There is no folder structure, but it is possible to later -apply certain hierarchical structures. It would be possible to create -a "folder structure", like the one mentioned above: click on -correspondent `repair company x`; then on tag `invoice`, then -`concerning=car` and `year=2019`. A UI could be created to present -exactly this hierarchy. Since I can't know your preferred structure -(not even my own…!), the docspell ui allows every combination, -regardless any hierarchies. You can first select a correspondent, then -a tag or the other way around. Usually it's not necessary to go very -deep. - -That's all about it! I thought why not try this approach and at the -same time learn about some technologies around. In the last year, -docspell evolved to a quite usable tool, imho. This was only possible, -because very nice people gave valueable feedback and ideas! - - -¹This is inspired by tools like -[mu](https://www.djcbsoftware.nl/code/mu/) and GMail. diff --git a/website/site/content/docs/query/_index.md b/website/site/content/docs/query/_index.md index 8a861be8..83c3a6e6 100644 --- a/website/site/content/docs/query/_index.md +++ b/website/site/content/docs/query/_index.md @@ -520,9 +520,9 @@ Find items with 2 or more attachments: attach.count>2 ``` -Find items with at least one tag invoice or todo: +Find items with at least one tag invoice or todo that are due next: ``` -tag:invoice,todo +tag:invoice,todo due>today ``` Find items with at least both tags invoice and todo: @@ -544,3 +544,14 @@ Find items within the last 30 days: ``` date>today;-30d ``` + +Find items with a custom field `paid` set to any value: +``` +f:paid:* +``` + +Find items that have been paid with more than $100 (using custom +fields `paid` as a date and `usd` as money): +``` +f:paid:* f:usd>100 +``` diff --git a/website/site/content/docs/tools/consumedir.md b/website/site/content/docs/tools/consumedir.md index 31afff40..2fc5a5f0 100644 --- a/website/site/content/docs/tools/consumedir.md +++ b/website/site/content/docs/tools/consumedir.md @@ -26,18 +26,29 @@ files. Example for watching two directories: ``` bash -./tools/consumedir.sh --path ~/Downloads --path ~/pdfs -m -dv http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ +./tools/consumedir.sh --path ~/Downloads --path ~/pdfs -m -dv \ + http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ ``` The script by default watches the given directories. If the `-o` or `--once` option is used, it will instead go through these directories -and upload all files in there. +and upload all files in there. For directory watching the +`inotifywait` command is used and must be present. Another way is to +use the `--poll` option. It expects the number of seconds to wait +between running itself with `--once`. + +Example using active polling (at 5 minutes interval): +``` bash +./tools/consumedir.sh --poll 300 --path ~/Downloads --path ~/pdfs -m -dv \ + http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ +``` Example for uploading all immediatly (the same as above only with `-o` added): ``` bash -$ consumedir.sh -o --path ~/Downloads --path ~/pdfs/ -m -dv http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ +$ ./tools/consumedir.sh --once --path ~/Downloads --path ~/pdfs/ -m -dv \ + http://localhost:7880/api/v1/open/upload/item/5DxhjkvWf9S-CkWqF3Kr892-WgoCspFWDo7-XBykwCyAUxQ ``` @@ -113,9 +124,9 @@ are some ideas to get around this limitation: 2. If option 1 is not possible for some reason, and you need to check a network filesystem, the only option left (that I know) is to periodically poll this directory. This is also possible with - consumedir, using the `-o` or `--once` option (see above). You'd - need to setup the systemd unit file a bit differently and add a - timer to it (or you can use cron or something more fancy…). + consumedir, using the `--poll` option (see above). You can also + setup a systemd timer to periodically run this script with the + `--once` option. 3. Copy the files to the machine that runs consumedir, via rsync for example. Note that this has no advantage over otpion 1, as you now need to setup rsync on the other machine to run either periodically diff --git a/website/site/templates/footer.html b/website/site/templates/footer.html index c6e85f49..f4a68a88 100644 --- a/website/site/templates/footer.html +++ b/website/site/templates/footer.html @@ -2,7 +2,7 @@
- Docspell, {{ config.extra.version }} + Docspell {{ config.extra.version }} • GPLv3+ @@ -12,7 +12,7 @@ • - Chat on Gitter + Chat on Gitter/Matrix