Merge pull request #6 from benoitblanc/doc_restructuration

Doc restructuration

Makefile

@@ -3,27 +3,27 @@ all:
 fetch:
 	no=1; \
 	for repo in qwc-map-viewer qwc-ogc-service qwc-feature-info-service qwc-fulltext-search-service qwc-legend-service qwc-permalink-service qwc-print-service  qwc-mapinfo-service qwc-data-service qwc-document-service qwc-elevation-service qwc-admin-gui qwc-registration-gui qwc-config-generator; do \
-		echo "+++\ntitle = \"$$repo\"\nmenuTitle = \"$$repo\"\nweight = $$no\n+++" >content/services/$$repo.md; \
-		curl -s -L https://github.com/qwc-services/$$repo/raw/master/README.md | sed '/^\[/d' >>content/services/$$repo.md; \
+		echo "+++\nmenuTitle = \"$$repo\"\nweight = $$no\nchapter = false\n+++" >content/installation/services/$$repo.md; \
+		curl -s -L https://github.com/qwc-services/$$repo/raw/master/README.md | sed '/^\[/d' >>content/installation/services/$$repo.md; \
 		no=$$((no+1)); \
 	done
 	no=1; \
 	for repo in qwc-db-auth qwc-ldap-auth; do \
-		echo "+++\ntitle = \"$$repo\"\nmenuTitle = \"$$repo\"\nweight = $$no\n+++" >content/authentication/$$repo.md; \
-		curl -s -L https://github.com/qwc-services/$$repo/raw/master/README.md | sed '/^\[/d' >>content/authentication/$$repo.md; \
+		echo "+++\nmenuTitle = \"$$repo\"\nweight = $$no\nchapter = false\n+++" >content/installation/authentication/$$repo.md; \
+		curl -s -L https://github.com/qwc-services/$$repo/raw/master/README.md | sed '/^\[/d' >>content/installation/authentication/$$repo.md; \
 		no=$$((no+1)); \
 	done
-	echo "+++\ntitle = \"QGIS Web Client 2\"\nmenuTitle = \"Viewer\"\nweight = 3\n+++\n" >content/viewer/_index.md; \
-	curl -s -L https://github.com/qgis/qwc2-demo-app/raw/master/doc/QWC2_Documentation.md >>content/viewer/_index.md;
+	echo "+++\nmenuTitle = \"Viewer\"\nweight = 3\nchapter = false\n+++\n" >content/installation/viewer/_index.md; \
+	curl -s -L https://github.com/qgis/qwc2-demo-app/raw/master/doc/QWC2_Documentation.md >>content/installation/viewer/_index.md;
 
 schemas:
 	# Convert JSON schemas to Markdown
 	# https://github.com/coveooss/json-schema-for-humans
 	no=1; \
 	for repo in qwc-map-viewer qwc-ogc-service qwc-feature-info-service qwc-fulltext-search-service qwc-legend-service qwc-permalink-service qwc-print-service  qwc-mapinfo-service qwc-data-service qwc-document-service qwc-elevation-service qwc-ext-service qwc-admin-gui qwc-registration-gui qwc-config-generator; do \
 		curl -s -o /tmp/schema.json -L https://github.com/qwc-services/$$repo/raw/master/schemas/$$repo.json; \
-		echo "+++\ntitle = \"$$repo\"\nweight = $$no\n+++" >content/configuration/$$repo.md; \
+		echo "+++\ntitle = \"$$repo\"\nweight = $$no\n+++" >content/installation/configuration/$$repo.md; \
 		.venv/bin/generate-schema-doc --config template_name=md /tmp/schema.json /tmp/schema.md; \
-		cat /tmp/schema.md >>content/configuration/$$repo.md; \
+		cat /tmp/schema.md >>content/installation/configuration/$$repo.md; \
 		no=$$((no+1)); \
 	done

content/setup/_index.md

@@ -0,0 +1,10 @@
+---
+title: "Setup"
+date: 2022-11-03T14:15:36+01:00
+chapter: true
+weight: 2
+---
+
+# Setup
+
+This section aims to explain how to install/deploy all of *QWC services*.

content/authentication/_index.md → content/setup/authentication/_index.md

@@ -1,7 +1,7 @@
 +++
 title = "Authentication"
 date = 2021-09-17T16:40:01+02:00
-weight = 6
+weight = 5
 chapter = true
 +++
 

content/authentication/qwc-db-auth.md → content/setup/authentication/qwc-db-auth.md

@@ -1,9 +1,12 @@
 +++
-title = "DB Authentication Service"
 menuTitle = "qwc-db-auth"
 weight = 1
+chapter = false
 +++
 
+Authentication with User DB
+===========================
+
 Authentication service with local user database.
 
 
@@ -50,11 +53,33 @@ A minimum password length of `8` with no other constraints is set by default. Op
 
 `password_min_length` and `password_max_length` can be set independently. `password_constraints` is a list of regular expression of which at least `password_min_constraints` have to match for the password to be valid, otherwise the `password_constraints_message` is shown. Note that the regular expression have to be JSON escaped and allow only patterns supported by Python's `re` module.
 
+If the `qwc_config.password_histories` table is present, additional optional password constraints may be set:
+```json
+"config": {
+  "password_expiry": 365,
+  "password_expiry_notice": 10,
+  "password_update_interval": 600,
+  "password_allow_reuse": false
+}
+```
+
+* `password_expiry` (default: `-1`): Number of days until a password expires, or `-1` to disable. Forces a password change once expired.
+* `password_expiry_notice` (default: `-1`): Show an expiry notice within this number of days before a password expires, or `-1` to disable
+* `password_update_interval` (default: `-1`): Min number of seconds before a password may be changed again, or `-1` to disable
+* `password_allow_reuse` (default: `true`): Set whether a user may reuse previous passwords or not
+
 Besides the form based DB login, an (insecure) plain POST login is supported. This method can be
 activated by setting `POST_PARAM_LOGIN=True`. User and password are passed as POST parameters
 `username` and `password`.
 Usage example: `curl -d 'username=demo&password=demo' http://localhost:5017/login`.
 
+Additional user info fields from `qwc_config.user_infos` may be added to the JWT identity by setting `user_info_fields`:
+```json
+"config": {
+  "user_info_fields": ["surname", "first_name"]
+}
+```
+
 * `MAIL_SERVER`: default ‘localhost’
 * `MAIL_PORT`: default 25
 * `MAIL_USE_TLS`: default False

content/authentication/qwc-ldap-auth.md → content/setup/authentication/qwc-ldap-auth.md

@@ -1,10 +1,11 @@
 +++
-title = "LDAP Authentication Service"
 menuTitle = "qwc-ldap-auth"
 weight = 2
+chapter = false
 +++
 
 Authentication with LDAP/Active Directory
+=========================================
 
 Configuration
 -------------

content/configuration/_index.md → content/setup/configuration/_index.md

@@ -1,7 +1,7 @@
 +++
 title = "Configuration"
 date = 2021-09-17T15:11:34+02:00
-weight = 3
+weight = 2
 chapter = false
 +++
 

content/quick-start/_index.md → content/setup/quick-start/_index.md

@@ -1,7 +1,7 @@
 +++
 title = "Quick Start"
 date = 2021-09-17T15:10:55+02:00
-weight = 2
+weight = 1
 chapter = false
 +++
 

content/services/qwc-admin-gui.md → content/setup/services/qwc-admin-gui.md

@@ -1,9 +1,12 @@
 +++
-title = "QWC Admin GUI"
 menuTitle = "qwc-admin-gui"
-weight = 13
+weight = 12
+chapter = false
 +++
 
+QWC Admin GUI
+=============
+
 GUI for administration of QWC Services.
 
 * manage users, groups and roles
@@ -120,6 +123,43 @@ Translation strings are stored in a JSON file for each locale in `translations/<
 
 Set the `DEFAULT_LOCALE` environment variable to choose the locale for the user notification mails (default: `en`).
 
+### Solr search index update
+
+If using a Solr search service, the Solr search index of a tenant may be updated via a button on the main page. This can be activated by adding the following configuration options to the Admin GUI service config:
+```json
+{
+  "config": {
+    "solr_service_url": "http://qwc-solr:8983/solr/gdi/",
+    "solr_tenant_dih": "dih_geodata",
+    "solr_tenant_dih_config_file": "/solr/config-in/dih_geodata_config.xml",
+    "solr_config_path": "/solr/config-out",
+    "solr_update_check_wait": 5,
+    "solr_update_check_max_retries": 10
+  }
+}
+```
+
+* `solr_service_url`: Solr Service base URL for collection
+* `solr_tenant_dih`: Solr DataImportHandler for the tenant
+* `solr_tenant_dih_config_file` (optional): Path to source DataImportHandler config file for the tenant
+* `solr_config_path` (optional): Path to Solr configs (**Note:** requires write permissions for DataImportHandler config files)
+* `solr_update_check_wait` (optional): Wait time in seconds for checks during Solr index update (default: `5`s)
+* `solr_update_check_max_retries` (optional): Max number of retries for checks during Solr index update (default: `10`)
+
+If both `solr_tenant_dih_config_file` and `solr_config_path` are set, the tenant config file is first copied to the Solr configs dir before updating the Solr search index.
+
+Example volumes for `qwc-docker` environment and above service config:
+```yaml
+services:
+  qwc-admin-gui:
+    # ...
+    volumes:
+      # ...
+      # Solr configs
+      - ./volumes/solr/configsets/gdi/conf:/solr/config-in:ro
+      - ./volumes/solr/data/gdi/conf:/solr/config-out
+```
+
 ### Plugins
 
 The admin gui is extendable through plugins, which reside in the `plugins` folder. To enable them, list them in `plugins` in the admin gui configuration. See the JSON schema for details, and for configuration parameters which may be required by plugins shipped by default with `qwc-admin-gui`.

content/services/qwc-config-generator.md → content/setup/services/qwc-config-generator.md

@@ -1,10 +1,13 @@
 +++
-title = "QWC Config Generator"
 menuTitle = "qwc-config-generator"
-weight = 15
+weight = 14
+chapter = false
 +++
 
-Generate JSON files for service configs and permissions from WMS GetCapabilities, QGS projects and QWC ConfigDB.
+QWC ConfigGenerator
+====================
+
+Generates JSON files for service configs and permissions from WMS GetCapabilities, QGS projects and QWC ConfigDB.
 
 
 Setup
@@ -29,7 +32,8 @@ Example `tenantConfig.json`:
     "qgis_projects_scan_base_dir": "/data/scan",
     "qgis_projects_gen_base_dir": "/data/gen",
     "permissions_default_allow": true,
-    "validate_schema": true
+    "validate_schema": true,
+    "autogen_keyvaltable_datasets": false
   },
   "themesConfig": {
       "defaultScales": [100000000, 50000000, 25000000, 10000000, 4000000, 2000000, 1000000, 400000, 200000, 80000, 40000, 20000, 10000, 8000, 6000, 4000, 2000, 1000, 500, 250, 100],
@@ -173,30 +177,24 @@ Example `tenantConfig.json`:
 
 For a full example see [tenantConfig-example.json](tenantConfig-example.json) ([JSON schema](schemas/qwc-config-generator.json)).
 
-*NOTE:* the QWC2 themes config is defined under `themesConfig` in the ConfigGenerator config and not in a separate file.
+*NOTE:* QWC2 themes are defined under `themesConfig` in the ConfigGenerator configuration and not in a separate file.
 
 QGIS projects can be automatically detected when `qgis_projects_scan_base_dir` is defined.
-For adding these projects, the following settings need to be defined in `themesConfig`.
+In order to have projects automatically added, the following settings need to be defined in `themesConfig`.
 
 - `defaultBackgroundLayers`
 - `defaultSearchProviders`
 - `defaultMapCrs`
 
-Additionally the config generator can also autodetect thumbnails when adding projects that meet the following criteria:
-
-- `qwc2_base_dir` is defined in the ConfigGenerator config
-- the thumbnail of the project is located in the QWC2 thumbnail directory (Example: `/qwc/assets/img/mapthumbs`)
-- the thumbnail image has the same filename as the QGIS project
-
-The config generator also has the ability to split a layer, that has been [classified](https://docs.qgis.org/3.16/en/docs/training_manual/vector_classification/classification.html) with QGIS, into multiple layers and move them into a new group (The group name will be the original layer name). The following steps need to be done, to activate this functionality:
+The ConfigGenerator can also autodetect thumbnails when adding projects. The projects have to meet the following criteria:
 
-1. Set ConfigGenerator config: `"split_categorized_layers": true`
+- `qwc2_base_dir` is defined in the ConfigGenerator configuration
+- the thumbnail of the project has to be located in the QWC2 thumbnail directory (Example: `/qwc/assets/img/mapthumbs`)
+- the thumbnail image needs to have the same filename as the QGIS project
 
-2. Define the environment variable `QGIS_APPLICATION_PREFIX_PATH` (default: `/usr`). The prefix path is the location where QGIS is installed on your system. This is needed by the split function, because it uses the `qgis.core` library.
+*NOTE:* the Search service configuration takes its resources directly from the ConfigGenerator configuration. Its Permissions are collected from the ConfigDB (`solr_facet` resources), unless they are defined in the ConfigGenerator configuration.
 
-*NOTE:* The Search service config takes its resources directly from the ConfigGenerator config. Its Permissions are collected from the ConfigDB (`solr_facet` resources), unless they are defined in the ConfigGenerator config.
-
-*NOTE:* the FeatureInfo service config may take additional WMS service resources and permissions directly from the ConfigGenerator config, e.g. for external info layers. Its Permissions are collected from the ConfigDB (`feature_info_service`, `feature_info_layer` resources), unless they are defined in the ConfigGenerator config. Example:
+*NOTE:* the FeatureInfo service configuration may take additional WMS service resources and permissions directly from the ConfigGenerator configuration, e.g. for external info layers. Its Permissions are collected from the ConfigDB (`feature_info_service`, `feature_info_layer` resources), unless they are defined in the ConfigGenerator configuration. Example:
 
 ```json
     {
@@ -258,9 +256,27 @@ The config generator also has the ability to split a layer, that has been [class
 ```
 
 
+### Split categorized layers
+
+The ConfigGenerator has also the ability to split a layer, that has been [classified](https://docs.qgis.org/3.16/en/docs/training_manual/vector_classification/classification.html) with QGIS, into multiple layers and move them into a new group (the group name will be the original layer name). The following steps need to be done, to activate this functionality:
+
+1. Place the projects whose layers you want to split below `<input_config_dir>/<tenant>/qgis_projects`.
+
+2. Ensure `qgis_projects_gen_base_dir` is set in the ConfigGenerator configuration, see the [schema definition](https://github.com/qwc-services/qwc-config-generator/blob/master/schemas/qwc-config-generator.json) for more details.
+
+3. In the ConfigGenerator configuration set: `"split_categorized_layers": true`
+
+4. If necessary, define the environment variable `QGIS_APPLICATION_PREFIX_PATH` (default: `/usr`). The prefix path is the location where QGIS is installed on your system (the split function needs this, because it uses the `qgis.core` library)
+
+5. For all layers that you want to split, create the [variable](https://docs.qgis.org/3.22/en/docs/user_manual/working_with_vector/vector_properties.html#variables-properties) 'convert_categorized_layer' and set it to 'true'.
+
+6. The ConfigGenerator will process the projects and write the modified projects to qgis_projects_gen_base_dir`. Hence, if for instance qgis_projects_base_dir=/data` and `qgis_projects_gen_base_dir=/data/gen`, the resource name for map `mymap` will be `gen/mymap`.
+
+*NOTE:* If you are using the qwc-config-generator Docker images, make sure you are using `qwc-config-generator:v<version>` and not `qwc-config-generator:v<version>-noqgis`.
+
 ### Schema validation
 
-By default, the config-generator will validate the service configurations in `tenantConfig.json` against the schema definition of the service. This requires network access to `raw.githubusercontent.com`. You can disable the schema validation by setting `"validate_schema": false` in config-generator `config` block in `tenantConfig.json`.
+By default, the ConfigGenerator will validate the service configurations in `tenantConfig.json` against the schema definition of the service. The JSON Schemas are loaded from local files in `JSON_SCHEMAS_PATH`, or else downloaded from https://github.com/qwc-services/ if no schema files are present. You can disable the schema validation by setting `"validate_schema": false` in the ConfigGenerator's `config` block in `tenantConfig.json`.
 
 ### Permissions
 
@@ -301,10 +317,10 @@ Generate permissions file:
 
 ### Service
 
-Set the `INPUT_CONFIG_PATH` environment variable to the base dir for reading generator config files (default: `config-in/`).
-Set the `OUTPUT_CONFIG_PATH` environment variable to the base dir for writing service configs and permissions (default: `/tmp/`).
+Set the `INPUT_CONFIG_PATH` environment variable to the base directory where for the configuration files are that should be read by the ConfigGenerator (default: `config-in/`).
+Set the `OUTPUT_CONFIG_PATH` environment variable to the base directory where the ConfigGenerator should output service configurations and permissions (default: `/tmp/`).
 
-*NOTE:* Requires write permissions for config-generator docker user (`www-data`) in `OUTPUT_CONFIG_PATH` for writing service configs and permissions.
+*NOTE:* the ConfigGenerator's docker user (`www-data`) needs to have write permissions to the directory defined in `OUTPUT_CONFIG_PATH`!
 
 Base URL:
 
@@ -314,6 +330,15 @@ Generate both service configs and permissions for `default` tenant:
 
     curl -X POST "http://localhost:5010/generate_configs?tenant=default"
 
+### Update JSON schemas
+
+You can change the directory from where the ConfigGenerator reads its schemas via the `JSON_SCHEMAS_PATH` environment variable (default `/tmp/`).
+You can change the versions of the schemas that the ConfigGenerator uses for verification inside [schema-versions.json](schemas/schema-versions.json) (default: current `master`).
+
+Download JSON schemas:
+
+    python download_json_schemas.py
+
 
 Development
 -----------