From 2a172ce720a6ba2274bdda7ab1dc2f2381a3060f Mon Sep 17 00:00:00 2001 From: Eike Kettner Date: Mon, 4 Jan 2021 15:16:32 +0100 Subject: [PATCH] Remove fulltext recreate-key config value It's now in the admin routes, protected by the `admin-endpoint.secret`. --- docker/docspell.conf | 1 - .../src/main/resources/reference.conf | 13 ++---- .../scala/docspell/restserver/Config.scala | 2 +- nix/module-server.nix | 30 +++++++------ website/site/content/docs/api/intro.md | 33 +++++++++++--- website/site/content/docs/configure/_index.md | 44 ++++++++++++------- 6 files changed, 77 insertions(+), 46 deletions(-) diff --git a/docker/docspell.conf b/docker/docspell.conf index a1c35bd7..31716b87 100644 --- a/docker/docspell.conf +++ b/docker/docspell.conf @@ -13,7 +13,6 @@ docspell.server { # Configuration of the full-text search engine. full-text-search { enabled = true - recreate-key = "" solr = { url = "http://solr:8983/solr/docspell" } diff --git a/modules/restserver/src/main/resources/reference.conf b/modules/restserver/src/main/resources/reference.conf index b76082af..e7ec39f8 100644 --- a/modules/restserver/src/main/resources/reference.conf +++ b/modules/restserver/src/main/resources/reference.conf @@ -117,10 +117,13 @@ docspell.server { # installed the app and have access to the system. Normal users # should not have access and therefore a secret must be provided in # order to access it. + # + # This is used for some endpoints, for example: + # - re-create complete fulltext index: + # curl -XPOST -H'Docspell-Admin-Secret: xyz' http://localhost:7880/api/v1/admin/fts/reIndexAll admin-endpoint { # The secret. If empty, the endpoint is disabled. secret = "" - } # Configuration of the full-text search engine. @@ -132,14 +135,6 @@ docspell.server { # Currently the SOLR search platform is supported. enabled = false - # When re-creating the complete index via a REST call, this key - # is required. If left empty (the default), recreating the index - # is disabled. - # - # Example curl command: - # curl -XPOST http://localhost:7880/api/v1/open/fts/reIndexAll/test123 - recreate-key = "" - # Configuration for the SOLR backend. solr = { # The URL to solr diff --git a/modules/restserver/src/main/scala/docspell/restserver/Config.scala b/modules/restserver/src/main/scala/docspell/restserver/Config.scala index 8c9dd7b9..06b897df 100644 --- a/modules/restserver/src/main/scala/docspell/restserver/Config.scala +++ b/modules/restserver/src/main/scala/docspell/restserver/Config.scala @@ -59,7 +59,7 @@ object Config { } } - case class FullTextSearch(enabled: Boolean, recreateKey: Ident, solr: SolrConfig) + case class FullTextSearch(enabled: Boolean, solr: SolrConfig) object FullTextSearch {} diff --git a/nix/module-server.nix b/nix/module-server.nix index 8e31c8ed..d079f778 100644 --- a/nix/module-server.nix +++ b/nix/module-server.nix @@ -40,6 +40,9 @@ let header-value = "some-secret"; }; }; + admin-endpoint = { + secret = ""; + }; full-text-search = { enabled = false; solr = { @@ -49,7 +52,6 @@ let def-type = "lucene"; q-op = "OR"; }; - recreate-key = ""; }; auth = { server-secret = "hex:caffee"; @@ -343,6 +345,20 @@ in { ''; }; + admin-endpoint = mkOption { + type = types.submodule({ + options = { + secret = mkOption { + type = types.str; + default = defaults.admin-endpoint.secret; + description = "The secret used to call admin endpoints."; + }; + }; + }); + default = defaults.admin-endpoint; + description = "An endpoint for administration tasks."; + }; + full-text-search = mkOption { type = types.submodule({ options = { @@ -394,18 +410,6 @@ in { default = defaults.full-text-search.solr; description = "Configuration for the SOLR backend."; }; - recreate-key = mkOption { - type = types.str; - default = defaults.full-text-search.recreate-key; - description = '' - When re-creating the complete index via a REST call, this key - is required. If left empty (the default), recreating the index - is disabled. - - Example curl command: - curl -XPOST http://localhost:7880/api/v1/open/fts/reIndexAll/test123 - ''; - }; }; }); default = defaults.full-text-search; diff --git a/website/site/content/docs/api/intro.md b/website/site/content/docs/api/intro.md index c4bb68ca..cf2acf61 100644 --- a/website/site/content/docs/api/intro.md +++ b/website/site/content/docs/api/intro.md @@ -16,11 +16,14 @@ workflow. The "raw" `openapi.yml` specification file can be found [here](/openapi/docspell-openapi.yml). -The routes can be divided into protected and unprotected routes. The -unprotected, or open routes are at `/open/*` while the protected -routes are at `/sec/*`. Open routes don't require authenticated access -and can be used by any user. The protected routes require an -authenticated user. +The routes can be divided into protected, unprotected routes and admin +routes. The unprotected, or open routes are at `/open/*` while the +protected routes are at `/sec/*` and admin routes are at `/admin/*`. +Open routes don't require authenticated access and can be used by any +user. The protected routes require an authenticated user. The admin +routes require a special http header with a value from the config +file. They are disabled by default, you need to specify a secret in +order to enable admin routes. ## Authentication @@ -38,6 +41,26 @@ a "normal" http header. If a cookie header is used, the cookie name must be `docspell_auth` and a custom header must be named `X-Docspell-Auth`. + +## Admin + +There are some endpoints available for adminstration tasks, for +example re-creating the complete fulltext index or resetting a +password. These endpoints are not available to normal users, but to +admins only. Docspell has no special admin users, it simply uses a +secret defined in the configuration file. The person who installs +docspell is the admin and knows this secret (and may share it) and +requests must provide it as a http header `Docspell-Admin-Secret`. + +Example: re-create the fulltext index (over all collectives): + +``` bash +$ curl -XPOST -H "Docspell-Admin-Secret: test123" http://localhost:7880/api/v1/admin/fts/reIndexAll +``` + +To enable these endpoints, you must provide a secret in the +[configuration](@/docs/configure/_index.md#admin-endpoint). + ## Live Api Besides the statically generated documentation at this site, the rest diff --git a/website/site/content/docs/configure/_index.md b/website/site/content/docs/configure/_index.md index 1a5f3ddd..1ac7b928 100644 --- a/website/site/content/docs/configure/_index.md +++ b/website/site/content/docs/configure/_index.md @@ -73,6 +73,22 @@ H2 url = "jdbc:h2:///path/to/a/file.db;MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE;AUTO_SERVER=TRUE" ``` +## Admin Endpoint + +The admin endpoint defines some [routes](@/docs/api/intro.md#admin) +for adminstration tasks. This is disabled by default and can be +enabled by providing a secret: + +``` bash +... + admin-endpoint { + secret = "123" + } +``` + +This secret must be provided to all requests to a `/api/v1/admin/` +endpoint. + ## Full-Text Search: SOLR @@ -105,27 +121,21 @@ documentation](https://lucene.apache.org/solr/guide/8_4/installing-solr.html). That will provide you with the connection url (the last part is the core name). -While the `full-text-search.solr` options are the same for joex and -the restserver, there are some settings that differ. The restserver -has this additional setting, that may be of interest: +The `full-text-search.solr` options are the same for joex and the +restserver. + +There is an [admin route](@/docs/api/intro.md#admin) that allows to +re-create the entire index (for all collectives). This is possible via +a call: ``` bash -full-text-search { - recreate-key = "test123" -} +$ curl -XPOST -H "Docspell-Admin-Secret: test123" http://localhost:7880/api/v1/admin/fts/reIndexAll ``` -This key is required if you want docspell to drop and re-create the -entire index. This is possible via a REST call: - -``` bash -$ curl -XPOST http://localhost:7880/api/v1/open/fts/reIndexAll/test123 -``` - -Here the `test123` is the key defined with `recreate-key`. If it is -empty (the default), this REST call is disabled. Otherwise, the POST -request will submit a system task that is executed by a joex instance -eventually. +Here the `test123` is the key defined with `admin-endpoint.secret`. If +it is empty (the default), this call is disabled (all admin routes). +Otherwise, the POST request will submit a system task that is executed +by a joex instance eventually. Using this endpoint, the index will be re-created. This is sometimes necessary, for example if you upgrade SOLR or delete the core to