diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2509a584..72be43f9 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -15,18 +15,12 @@ jobs: submodules: true fetch-depth: 0 - - name: Setup Hugo - uses: peaceiris/actions-hugo@v2 - with: - hugo-version: '0.68.3' - # extended: true - - name: Build - run: hugo --minify + run: ./build.sh --update - name: Deploy uses: peaceiris/actions-gh-pages@v3 if: github.ref == 'refs/heads/main' with: github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./public + publish_dir: ./site diff --git a/.gitignore b/.gitignore index c75eeccc..d825f102 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -/public +/site +/.venv diff --git a/Makefile b/Makefile deleted file mode 100644 index c1eebde1..00000000 --- a/Makefile +++ /dev/null @@ -1,33 +0,0 @@ -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 "+++\nmenuTitle = \"$$repo\"\nweight = $$no\nchapter = false\n+++" >content/setup/services/$$repo.md; \ - curl -s -L https://github.com/qwc-services/$$repo/raw/master/README.md | sed '/^\[/d' >>content/setup/services/$$repo.md; \ - no=$$((no+1)); \ - done - no=1; \ - for repo in qwc-db-auth qwc-ldap-auth; do \ - echo "+++\nmenuTitle = \"$$repo\"\nweight = $$no\nchapter = false\n+++" >content/setup/authentication/$$repo.md; \ - curl -s -L https://github.com/qwc-services/$$repo/raw/master/README.md | sed '/^\[/d' >>content/setup/authentication/$$repo.md; \ - no=$$((no+1)); \ - done - no=1; \ - for file in requirements quick_start qwc_configuration url_parameters startup_position server_side_configuration keeping_qwc_up_to_date developing; do \ - echo "+++\nmenuTitle = \"$$file\"\nweight = $$no\nchapter = false\n+++" >content/setup/viewer/$$file.md; \ - curl -s -L https://github.com/qgis/qwc2-demo-app/raw/master/doc/src/$$file.md | sed '/^\[/d' >>content/setup/viewer/$$file.md; \ - no=$$((no+1)); \ - done - -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/setup/configuration/$$repo.md; \ - .venv/bin/generate-schema-doc --config template_name=md /tmp/schema.json /tmp/schema.md; \ - cat /tmp/schema.md >>content/setup/configuration/$$repo.md; \ - no=$$((no+1)); \ - done diff --git a/README.md b/README.md index 82215e19..847b277c 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,15 @@ -QWC Site -======== +QWC2 Documentation +================== -Homepage and documentation of QWC2 and QWC Services. +Work in progress. +Build +===== -Development ------------ +Full build, fetching the service configuration schemas and plugin reference: -Requires [Hugo](https://gohugo.io/). + ./build.sh --update -Get site code: +Build using previously downloaded service configuration schemas and plugin reference: - git clone --recursive https://github.com/qwc-services/qwc-services.github.io.git - -Run Hugo: - - hugo serve + ./build.sh diff --git a/archetypes/default.md b/archetypes/default.md deleted file mode 100644 index 00e77bd7..00000000 --- a/archetypes/default.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "{{ replace .Name "-" " " | title }}" -date: {{ .Date }} -draft: true ---- - diff --git a/build.sh b/build.sh new file mode 100755 index 00000000..72dc1855 --- /dev/null +++ b/build.sh @@ -0,0 +1,46 @@ +#!/bin/sh + +echo "* Setting up venv..." +rm -rf .venv +python3 -mvenv .venv +source .venv/bin/activate +pip install -r requirements.txt + +if [ "$1" == "--update" ]; then +echo "# References" > src/references/index.md +echo "" >> src/references/index.md + +echo "* Downloading plugin reference..." +wget -q -O src/references/qwc2_plugins.md https://raw.githubusercontent.com/qgis/qwc2-demo-app/master/doc/src/plugins.md +echo "* [QWC2 plugins](qwc2_plugins.md)" >> src/references/index.md + +mkdir -p tmp +echo "* Downloading schema versions..." +wget -q -O tmp/schema-versions-master.json https://github.com/qwc-services/qwc-config-generator/raw/master/schemas/schema-versions-master.json + +for schemaUrl in \ + https://github.com/qwc-services/qwc-config-generator/raw/master/schemas/qwc-config-generator.json \ + $(cat tmp/schema-versions-master.json | grep schema_url | awk -F'"' '{print $4}'); +do + service=$(basename ${schemaUrl%.json}) + echo "* Generating service schema reference for $service..." + echo $schemaUrl + wget -q -O tmp/$service.json $schemaUrl + generate-schema-doc tmp/$service.json src/references/$service.md + + echo "* [$service]($service.md)" >> src/references/index.md + +done +rm -rf tmp +fi + +echo "* Clean previous HTML build..." +rm -rf site + +echo "* Building HTML..." +mkdocs build -f qwc2.yml + +# cleanup venv +echo "* Clean venv..." +deactivate +rm -rf .venv diff --git a/config.toml b/config.toml deleted file mode 100644 index b63bedfd..00000000 --- a/config.toml +++ /dev/null @@ -1,17 +0,0 @@ -baseURL = "https://qwc-services.github.io/" -languageCode = "en-us" -title = "QWC2 Documentation" - -# https://learn.netlify.app/ -theme = "hugo-theme-learn" - -[params] -editURL = "https://github.com/qwc-services/qwc-services.github.io/edit/main/content/" -description = "Documentation QWC2 and QWC services" -themeVariant = "green" -disableNextPrev = true -disableMermaid = true - -# For search functionality -[outputs] -home = [ "HTML", "RSS", "JSON"] diff --git a/content/_index.md b/content/_index.md deleted file mode 100644 index 26fb76f9..00000000 --- a/content/_index.md +++ /dev/null @@ -1,46 +0,0 @@ -+++ -title = "QWC2 / QWC Services" -date = 2021-09-17T15:11:57+02:00 -+++ - -# QWC2 / QWC Services - -QGIS Web Client 2 (QWC2) and QWC Services on the backend provide a complete Web GIS infrastructure. - - -## QWC2 viewer - -* Modern responsive viewer -* Optimized for QGIS server -* Customizable and extensible - -![](/images/viewer.jpg) - -## Powerful features - -* Fulltext search -* Info templates -* Customizable edit forms -* PDF printing and reporting - - -## Enterprise ready - -* Docker/Kubernetes or WSGI deployments -* Multi-tenant setup -* Custom service integration -* Multiple authentication backends - -![](/images/search.png) - -## Explore - -* [Overview](/overview/) -* [Quickstart](/quick-start/) -* Public viewers: [Demo](http://qwc2.sourcepole.ch) | [Glarus](https://map.geo.gl.ch/) | [Solothurn](https://geo.so.ch/map/) | [qgisweb.oslandia.net](https://qgisweb.oslandia.net/) | [Erft Verband](http://webgis.erftverband.de) - -## Support - -* Community support: [Github](https://github.com/qgis/qwc2-demo-app/issues) -* Commercial Support: [Sourcepole](https://www.sourcepole.com/) and other companies. -* [Improve this web site](https://github.com/qwc-services/qwc-services.github.io/) diff --git a/content/overview/_index.en.md b/content/overview/_index.en.md deleted file mode 100644 index b1f9c827..00000000 --- a/content/overview/_index.en.md +++ /dev/null @@ -1,115 +0,0 @@ -+++ -title = "Overview" -date = 2021-09-17T15:56:40+02:00 -weight = 1 -chapter = false -+++ - -The QWC Services are a collection of microservices providing configurations for and authorized access to different QWC Map Viewer components. - -![qwc-services-arch](/images/qwc-services-arch.png) - -A QWC services SDI has the following main components: -- **Auth-Service**: Authentication service. Currently supported: User DB, LDAP/AD, SAML or Kerberos. -- **Map Viewer**: QWC2 Webclient with configered tools, open and protected maps. -- **OGC Service**: Frontend with access control for WMS and WFS. -- **REST Services**: Services providing an API for Search, Mapinfo, etc. -- **QGIS Server**: Server for map rendering (WMS) and WFS publication. -- **Solr**: Apache Solr fulltext search engine. Backend for geodata and metadata search. -- **Reporting Server**: Jasper Reporting server. -- **Admin GUI**: Administration UI for managing users, permissions, etc. - -### User- and access control managment - -For authentication the following services are currently provided: - - - qwc-db-auth: Integrated User-DB - - qwc-ldap-auth: LDAP / Active Directory - - qwc-saml-auth: SAML 2.0 - - qwc-kerberos-auth: Kerberos - -The config/user DB is used in all authentication methods for managing permissions. - -After successful identification, all authentcation services issue a JWT -token which is forwarded to other services either as session cookie or via -HTTP header. -The JWT token contains username and roles of the authenticated user. Services -requring authentication use a common library for reading the JWT content -and checking the cryptographic signature. - -Authorization is managed by each service. Services like QGIS server, which -don't have built-in permission control, are protected by frontend services -like "«qwc-ogc-service". - -**Groups and roles** - -Different permissions (e.g. read or write) for accessing resources can -be granted to "roles". Roles are associated with users or user groups. -A user can be member of multiple groups and can also have multiple direct roles. - -![](/images/100002010000019100000075E735E86EF7DB022F.png) - -If an authentication service returns group information from an IDP, group -permissions can be directly used, without registering individual users. - -### REST API - -qwc-services communinicate via REST APIs, which are documented according to -the OpenAPI specification. - -![Illustration 2: OpenAPI Dokumentation Data -Service](/images/swagger.jpg) - -### Search - -Apache Solr () is used as integrated search engine. -The fulltext search engine with faceted search capabilities is available -with an Apache license and is used by internet search engines like -DuckDuckGo. - -Search categories ("facets") can be configured as globally available for -maps or dependent on active layers only. An assigned "filterword" can be -used as shortcut for limiting searches on a category. - -![](/images/search.png) - -Grouping and sorting of search results is dependent on the result count -per category. If many results are available, an additional section -for search refining is showed in the results. There is also a history -of recent searches. - -### Information query - -Map info queries are handled by the qwc-feature-info-service providing -an WMS GetFeatureInfo API. - -The following info query types can be configured for each layer:: - - - WMS feature info query (default): Forwarded to QGIS Server - - DB Query: Execution of a user-defined SQL query - - Custom Info module: Specific Python module for returning layer information - -Result data of the query module is rendered with the Jinja template engine (with -customizable HTML templates) and returned to the web client as GetFeatureInfoResponse. - -![](/images/feature-info.png) - -### Measuring tools - -Tools for position, distance, area and heading measurements are provided. Units are -user selecteable. - -The qwc-elevation-service returns height profiles for distance measurements. The -mouse position in the height profile is marked in the map and shows a distance -height measurement. - -![](/images/measure.png). - -### Printing - -Printing layouts included in QGIS projects can be used for printing. -Users can select permitted layouts in the print dialog. System provided information -like print date, scale bar, coordinate systems, north arraw and scale can -be used in the priint layout. - -User editable text fields like map title or remarks can be provided as well. diff --git a/content/overview/overview.de.md b/content/overview/overview.de.md deleted file mode 100644 index 82b36a09..00000000 --- a/content/overview/overview.de.md +++ /dev/null @@ -1,164 +0,0 @@ -+++ -title = "Übersicht" -date = 2021-09-17T15:56:40+02:00 -weight = 1 -draft = true -+++ - -The QWC Services are a collection of microservices providing configurations for and authorized access to different QWC Map Viewer components. - -![qwc-services-arch](/images/qwc-services-arch.png) - -Die GDI besteht aus folgenden Server-Komponenten: -- **Auth-Service**: Es werden verschiedene Authentisierungs-Methoden unterstützt. Z.B. HTTP Basic Authentication mit User-DB, AD/LDAP, SAML und Kerberos. - Die direkt zugänglichen Dienste enthalten eine Autorisierungsschicht für alle Zugriffe. -- **Map Viewer**: QWC2 Webclient mit konfigurierten Tools, offenen und zugriffsgeschützten Karten. -- **OGC Service**: Frontend mit Zugriffskontrolle für WMS und WFS. -- **REST Services**: API Funktionen wie Search, GetLegend, etc. -- **QGIS Server WMS/WFS**: Server für Kartendienste (WMS) und Datendienste (WFS) -- **Solr**: Apache Solr Search-Engine. Dient als Backend für die Suche von Geodaten und Metadaten. -- **Reporting-Server**: Server-Komponente zur Erzeugung von Reports. -- **Administration**: Adminstrations-GUI für die Verwaltung von Usern, Rechten, Metadaten, etc. - -### User- und Zugriffsmanagement - -Für die Authentifizierung stehen folgende Services zur Verfügung: - - - qwc-db-auth: Integrierte User-DB - - qwc-ldap-auth: LDAP / Active Directory - - qwc-saml-auth: SAML 2.0 - - qwc-kerberos-auth: Kerberos - -Die User-DB ist wird bei allen Authentisierungsmethoden benutzt, um -Usern weitergehende Rechte zu vergeben. - -Alle Authentisierungsdienste stellen nach erfolgreicher Identifikation -ein JWT-Token aus, welches mit einem Session-Cookie oder via HTTP-Header -an die Dienste weitergeleitet wird. Das JWT-Token enthält den Usernamen -und die Rollen des Users. Die Dienste nutzen eine gemeinsame Bibliothek -zur Verarbeitung des Tokens. Diese stellt sicher, dass die -kryptographische Signatur des Tokens geprüft wird. - -Die Authorisierung wird von den einzelnen Diensten sichergestellt. Für -den Dienstserver übernimmt der vorgeschaltete Service «qwc-ogc-service» -die Authorisierung. - -**Gruppen und Rollen** - -Einem User werden Zugriffsberechtigungen zu Ressourcen zugeordnet, oder -umgekehrt jeder Ressource eine Liste der jeweils zugelassenen Benutzer. - -Mit dem Konzept von Benutzergruppen und Rollen lassen sich -Berechtigungen zusammenfassen. User können in Gruppen organisiert -werden. Werden vom Authentisierungsservice Gruppen-Informationen von -einem IDP übernommen, dann können die Gruppenrechte auch ohne Erfassung -der Userinformationen angewandt werden. - -Zugriffsrechte, werden in einer Rollendefinition zusammengefasst. Eine -Auflistung von Zugriffsrechten wird häufig auch auch Access Control List -(ACL) genannt. - -Diese Rollen (eine oder mehrere) können Usern oder Gruppen zugeordnet werden. - -![](/images/100002010000019100000075E735E86EF7DB022F.png) - - -### REST-API - -Die qwc-services werden über ein REST-API angesprochen. Dieses ist in -Form einer OpenAPI-Spezifikation dokumentiert. - -![Illustration 2: OpenAPI Dokumentation Data -Service](/images/10000201000006C1000007848FFF3358691E995D.png) - -Der config-service, welcher für die Verwaltung der -Service-Konfigurationen und -Permissions zuständig ist, hat ein intern -zugängliches API für den Update einer Konfiguration und -Abfrage-Funktionen. - -### Legende - -Der qwc-legend-service unterstützt die Erstellung von Legenden via -Dienstserver oder die Aufbereitung der Legende mit konfigurierten -Bildern. So können dynamische Legenden mit automatisch vom Kartenserver -generierten Legenden, sowie manuell erstellte Legenden kombiniert -werden. - -![](/images/100002010000013F000002C91A6324D14C5FD85E.png) - -### Suche - -Als Search-Engine wird Apache Solr () -integriert. Die Volltext Search-Engine mit «Facet»-Suche ist unter der -Apache Lizenz erhältlich und wird unter anderem von -Internetsuchmaschinen wie DuckDuckGo eingesetzt. - -Für den Viewer können abhängig vom Thema Suchkategorieren definiert -werden, die immer berücksichtigt werden und einzelnen Layern können -Suchkategrien zugeordnet werden, welche nur bei aktiver Layeranzeige -verwendet werden. Einem Layer kann ein Filterwort zugeordnet werden, -welches zur Kategorieneinschränkung im Viewer verwendet werden kann. - -![](/images/search.png) - -Die Gruppierung und Sortierung der Resultate erfolgt abhängig von der -Anzahl Treffer innerhalb der Kategorieren. Bei einer grossen Trefferzahl -wird der Abschnitt zur Verfeinerung der Suche aufgeklappt. Es wird eine -History der letzten Suchbegriffen geführt. - -### Informationsabfrage - -Informationsabfragen werden über den qwc-feature-info-service -abgehandelt. Die Abfrage erfolgt mit dem WMS GetFeatureInfo-API auf eine -geographische Position und bestimmte Layer. - -Für jeden Layer kann eine der folgenden Arten zur Informationsabfrage -konfiguriert werden: - - - WMS Geoinformation (Standard): Weiterleitung an QGIS Server - - DB Query: Ausführung einer konfigurierten DB-Query - - Custom Info-Modul: Spezifisches Python-Modul zur Rücklieferung der - Layer-Info - -Die Resultate des Abfragemoduls werden mittels eines konfigurierbaren -HTML-Templates gerendert und als GetFeatureInfoResponse an den Webclient -zurückgeliefert. - -![](/images/feature-info.png) - -### Messen - -Es stehen Messwerkzeuge für Position, Länge, Fläche und Richtung zur -Verfügung. Masseinheiten sind vom User wählbar. - -Der qwc-elevation-service -liefert auf Anfrage ein Höhenprofil zurück, welches bei der -Längenmessung angezeigt werden kann. Die Mausposition im Profil wird in -der Karte markiert und mit Distanzangabe und Höhe -versehen - -![](/images/measure.png). - -### Drucken - -Der Kartendruck erfolgt über vordefinierte Druckvorlagen. Die -Druckvorlagen werden mit QGIS als Layout erstellt und gepflegt. Dabei -ist es möglich sehr hochwertige und flexible Kartenvorlagen zu erstellen -mit einer Auflösung bis zu 1200dpi zu erstellen. Die vordefinierten -Druckvorlagen stehen dem Benutzer über eine Auswahlliste im QWC2 Client -zur Verfügung. Für beliebige Fachkarten können kartenspezifische -Druckvorlagen erstellt werden. Systemgesteuerte Angaben wie Druckdatum, -Massstabsleiste, Referenzkoordinaten, Nordpfeil und Massstabszahl sowie -viele weitere Informationen sind in den Druckvorlagen integrierbar. - -Editierbare Textfelder die durch den Benutzer angepasst werden können -(z.B. Kartentitel, Bemerkungen etc.) sind verfügbar. Die frei -editierbaren Textfelder bleiben beim Wechsel der Druckvorlage (z.B. A4 -quer zu A4 hoch) erhalten. - -Vor dem Druck kann der Anwender im QWC2-Client den gewünschten -Druckmassstab einstellen. Es werden sowohl eine Massstabsliste als auch -ein frei wählbarer Massstab angeboten. - -Nach dem der Ausdruck aufbereitet wurde wird dem Anwender die gewünschte -Karte in gewünschter Auflösung als PDF zum Download angeboten. diff --git a/content/setup/_index.md b/content/setup/_index.md deleted file mode 100644 index c9eacda2..00000000 --- a/content/setup/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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*. \ No newline at end of file diff --git a/content/setup/authentication/_index.md b/content/setup/authentication/_index.md deleted file mode 100644 index ee9b1294..00000000 --- a/content/setup/authentication/_index.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -title = "Authentication" -date = 2021-09-17T16:40:01+02:00 -weight = 6 -chapter = true -+++ - -# Authentication services diff --git a/content/setup/authentication/qwc-db-auth.md b/content/setup/authentication/qwc-db-auth.md deleted file mode 100644 index 03d66e10..00000000 --- a/content/setup/authentication/qwc-db-auth.md +++ /dev/null @@ -1,149 +0,0 @@ -+++ -menuTitle = "qwc-db-auth" -weight = 1 -chapter = false -+++ - -Authentication with User DB -=========================== - -Authentication service with local user database. - - -Configuration -------------- - -The static config files are stored as JSON files in `$CONFIG_PATH` with subdirectories for each tenant, -e.g. `$CONFIG_PATH/default/*.json`. The default tenant name is `default`. - -### DB Auth Service config - -* [JSON schema](schemas/qwc-db-auth.json) -* File location: `$CONFIG_PATH//dbAuthConfig.json` - -Example: -```json -{ - "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-db-auth/master/schemas/qwc-db-auth.json", - "service": "db-auth", - "config": { - "db_url": "postgresql:///?service=qwc_configdb" - } -} -``` - -Set the `MAX_LOGIN_ATTEMPTS` environment variable to set the maximum number of -failed login attempts before sign in is blocked (default: `20`). - -A minimum password length of `8` with no other constraints is set by default. Optional password complexity constraints can be set using the following `config` options: -```json -"config": { - "password_min_length": 8, - "password_max_length": 128, - "password_constraints": [ - "[A-Z]", - "[a-z]", - "\\d", - "[ !\"#$%&'()*+,\\-./\\\\:;<=>?@\\[\\]^_`{|}~]" - ], - "password_min_constraints": 3, - "password_constraints_message": "Password must contain at least three of these character types: uppercase letters, lowercase letters, numbers, special characters" -} -``` - -`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 -* `MAIL_USE_SSL`: default False -* `MAIL_DEBUG`: default app.debug -* `MAIL_USERNAME`: default None -* `MAIL_PASSWORD`: default None -* `MAIL_DEFAULT_SENDER`: default None -* `MAIL_MAX_EMAILS`: default None -* `MAIL_SUPPRESS_SEND`: default app.testing -* `MAIL_ASCII_ATTACHMENTS`: default False - -In addition the standard Flask `TESTING` configuration option is used by Flask-Mail in unit tests. - -### Two factor authentication - -Two factor authentication using TOTP can be enabled by setting the environment variable `TOTP_ENABLED=True`. -This will require an additional verification token after sign in, based on the user's TOTP secret. - -A personal QR code for setting up the two factor authentication is shown to the user on first sign in (or if the TOTP secret is empty). -The TOTP issuer name for your application can be set using the environment variable `TOTP_ISSUER_NAME="QWC Services"`. - -An user's TOTP secret can be reset by clearing it in the Admin GUI user form. - - -Usage ------ - -Run standalone application: - - python server.py - -Endpoints: - - http://localhost:5017/login - - http://localhost:5017/logout - - -Development ------------ - -Create a virtual environment: - - virtualenv --python=/usr/bin/python3 .venv - -Activate virtual environment: - - source .venv/bin/activate - -Install requirements: - - pip install -r requirements.txt - -Set the `CONFIG_PATH` environment variable to the path containing the service config and permission files when starting this service (default: `config`). - - export CONFIG_PATH=../qwc-docker/volumes/config - -Configure environment: - - echo FLASK_ENV=development >.flaskenv - export MAIL_SUPPRESS_SEND=True - export MAIL_DEFAULT_SENDER=from@example.com - -Start local service: - - python server.py diff --git a/content/setup/authentication/qwc-ldap-auth.md b/content/setup/authentication/qwc-ldap-auth.md deleted file mode 100644 index 047c560f..00000000 --- a/content/setup/authentication/qwc-ldap-auth.md +++ /dev/null @@ -1,68 +0,0 @@ -+++ -menuTitle = "qwc-ldap-auth" -weight = 2 -chapter = false -+++ - -Authentication with LDAP/Active Directory -========================================= - -Configuration -------------- - -See also [flask-ldap3-login](https://flask-ldap3-login.readthedocs.io/en/latest/configuration.html) - -ENV | default value | description ---------------------------------|-------------------------|--------- -`JWT_SECRET_KEY` | `********` | secret key for JWT token (same for all services) -`LDAP_HOST` | `localhost` | Hostname of your LDAP Server -`LDAP_PORT` | `389` | The port number of your LDAP server. -`LDAP_USE_SSL` | `False` | Set to True if your server uses SSL -`LDAP_BASE_DN` | `dc=example,dc=org` | Base DN of your directory -`LDAP_USER_DN` | `ou=users` | Users DN to be prepended to the Base DN -`LDAP_GROUP_DN` | `ou=groups` | Groups DN to be prepended to the Base DN -`LDAP_SEARCH_FOR_GROUPS` | `False` | Search for groups -`LDAP_GROUP_SEARCH_SCOPE` | `LEVEL` | Specifies what scope to search in when searching for a specific group -`LDAP_GROUP_OBJECT_FILTER` | `(objectclass=group)` | Specifies what object filter to apply when searching for groups -`LDAP_GROUP_MEMBERS_ATTR` | `uniqueMember` | Specifies the LDAP attribute where group members are declared -`LDAP_GROUP_NAME_ATTRIBUTE` | `cn` | Group name attribute in LDAP group response -`LDAP_GET_GROUP_ATTRIBUTES` | `*` (ALL_ATTRIBUTES) | Specifies which LDAP attributes to get when searching LDAP for a group/groups -`LDAP_USER_SEARCH_SCOPE` | `LEVEL` | Specifies what scope to search in when searching for a specific user -`LDAP_USER_RDN_ATTR` | `cn` | The RDN attribute for your user schema on LDAP -`LDAP_USER_LOGIN_ATTR` | `cn` | The Attribute you want users to authenticate to LDAP with -`LDAP_BIND_USER_DN` | `None` | The Username to bind to LDAP with -`LDAP_BIND_USER_PASSWORD` | `None` | The Password to bind to LDAP with - - -Usage ------ - -Run standalone application: - - python server.py - -Endpoints: - - http://localhost:5017/login - - http://localhost:5017/logout - - -Development ------------ - -Create a virtual environment: - - virtualenv --python=/usr/bin/python3 .venv - -Activate virtual environment: - - source .venv/bin/activate - -Install requirements: - - pip install -r requirements.txt - -Start local service: - - python server.py diff --git a/content/setup/configuration/_index.md b/content/setup/configuration/_index.md deleted file mode 100644 index 5618a6a2..00000000 --- a/content/setup/configuration/_index.md +++ /dev/null @@ -1,122 +0,0 @@ -+++ -title = "Configuration" -date = 2021-09-17T15:11:34+02:00 -weight = 3 -chapter = false -+++ - -## Configuration database - -The [Configuration database](https://github.com/qwc-services/qwc-config-db) (ConfigDB) contains the database schema `qwc_config` for configurations and permissions of QWC services. - -This database uses the PostgreSQL connection service `qwc_configdb` by default, which can be setup for the corresponding database in the PostgreSQL connection service file `pg_service.conf`. This default can be overridden by setting the environment variable `CONFIGDB_URL` to a custom DB connection string (see [below](#service-configurations)). - -Additional user fields are saved in the table `qwc_config.user_infos` with a a one-to-one relation to `qwc_config.users` via the `user_id` foreign key. -To add custom user fields, add new columns to your `qwc_config.user_infos` table and set your `USER_INFO_FIELDS` accordingly (see [below](#service-configurations)). - - -### Database migrations - -An existing ConfigDB can be updated to the latest schema by running the database migrations from the `qwc-config-db` directory: - - cd qwc-config-db/ - git pull - alembic upgrade head - - -## Service configurations - -The QWC Services are generally configured using environment variables. -These can be set when running the services locally or in `docker-compose.yml` when using Docker. - -Common configuration: - -ENV | default value | description -----------------------|--------------------|--------- -`CONFIG_PATH` | . | Base path for service configuration files -`JWT_SECRET_KEY` | `********` | secret key for JWT token -`TENANT_URL_RE` | None | Regex for tenant extraction from base URL. Example: ^https?://.+?/(.+?)/ -`TENANT_HEADER` | None | Tenant Header name. Example: Tenant - - -See READMEs of services for details. - - -## Resources and Permissions - -Permissions and configurations are based on different resources with assigned permissions in the [configuration database](https://github.com/qwc-services/qwc-config-db). -These can be managed in the [QWC configuration backend](https://github.com/qwc-services/qwc-admin-gui). - - -### Resources - -The following resource types are available: - -* `map`: WMS corresponding to a QGIS Project - * `layer`: layer of a map - * `attribute`: attribute of a map layer - * `print_template`: print composer template of a QGIS Project - * `data`: Data layer for editing - * `attribute`: attribute of a data layer - * `data_create`: Data layer for creating features - * `data_read`: Data layer for reading features - * `data_update`: Data layer for updating features - * `data_delete`: Data layer for deleting features -* `viewer`: custom map viewer configuration -* `viewer_task`: permittable viewer tasks - -The resource `name` corresponds to the technical name of its resource (e.g. WMS layer name). - -The resource types can be extended by inserting new types into the `qwc_config.resource_types` table. -These can be queried, e.g. in a custom service, by using `PermissionClient::resource_permissions()` or -`PermissionClient::resource_restrictions()` from [QWC Services Core](https://github.com/qwc-services/qwc-services-core). - -Available `map`, `layer`, `attribute` and `print_template` resources are collected from WMS `GetProjectSettings` and the QGIS projects. - -`data` and their `attribute` resources define a data layer for the [Data service](https://github.com/qwc-services/qwc-data-service). -Database connections and attribute metadata are collected from the QGIS projects. - -For more detailed CRUD permissions `data_create`, `data_read`, `data_update` and `data_delete` can be used instead of `data` -(`data` and `write=False` is equivalent to `data_read`; `data` and `write=True` is equivalent to all CRUD resources combined). - -The `viewer` resource defines a custom viewer configuration for the map viewer (see [Custom viewer configurations](https://github.com/qwc-services/qwc-map-viewer#custom-viewer-configurations)). - -The `viewer_task` resource defines viewer functionalities (e.g. printing or raster export) that can be restricted or permitted. -Their `name` (e.g. `RasterExport`) corresponds to the `key` in `menuItems` and `toolbarItems` in the QWC2 `config.json`. Restricted viewer task items are then removed from the menu and toolbar in the map viewer. Viewer tasks not explicitly added as resources are kept unchanged from the `config.json`. - - -### Permissions - -Permissions are based on roles. Roles can be assigned to groups or users, and users can be members of groups. -A special role is `public`, which is always included, whether a user is signed in or not. - -Each role can be assigned a permission for a resource. -The `write` flag is only used for `data` resources and sets whether a data layer is read-only. - -Based on the user's identity (user name and/or group name), all corresponding roles and their permissions and restrictions are collected. -The service configurations are then modified according to these permissions and restrictions. - -Using the `DEFAULT_ALLOW` environment variable, some resources can be set to be permitted or restricted by default if no permissions are set (default: `False`). Affected resources are `map`, `layer`, `print_template` and `viewer_task`. - -e.g. `DEFAULT_ALLOW=True`: all maps and layers are permitted by default -e.g. `DEFAULT_ALLOW=False`: maps and layers are only available if their resources and permissions are explicitly configured - - -## Group registration - -Using the optional [Registration GUI](https://github.com/qwc-services/qwc-registration-gui) allows users to request membership or unsubscribe from registrable groups. These requests can then be accepted or rejected in the [Admin GUI](https://github.com/qwc-services/qwc-admin-gui). - -Workflow: -* Admin GUI - * admin user creates new groups with assigned roles and permissions on resources - * admin user configures registrable groups -* Registration GUI - * user select desired groups from registrable groups and submits application form - * admin users are notified of new registration requests -* Admin GUI - * admin user selects entry from list of pending registration requests - * admin user accepts or rejects registration requests for a user - * user is added to or removed from accepted groups - * user is notified of registration request updates -* Map Viewer - * user permissions are updated for new groups diff --git a/content/setup/quick-start/_index.md b/content/setup/quick-start/_index.md deleted file mode 100644 index 9d833968..00000000 --- a/content/setup/quick-start/_index.md +++ /dev/null @@ -1,137 +0,0 @@ -+++ -title = "Quick Start" -date = 2021-09-17T15:10:55+02:00 -weight = 2 -chapter = false -+++ - -### Docker containers for QWC services - -Create a QWC services dir: - - mkdir qwc-services - cd qwc-services/ - -Clone [Docker containers for QWC services](https://github.com/qwc-services/qwc-docker): - - git clone https://github.com/qwc-services/qwc-docker.git - -Install Docker and setup containers (see [qwc-docker README](https://github.com/qwc-services/qwc-docker#quick-start)): - - cd qwc-docker/ - cp docker-compose-example.yml docker-compose.yml - cp api-gateway/nginx-example.conf api-gateway/nginx.conf - -Create a secret key: - - python3 -c 'import secrets; print("JWT_SECRET_KEY=\"%s\"" % secrets.token_hex(48))' >.env - -Set permissions for writable volumes: - - # The containers use UID 33 for www-data - sudo chown -R 33:33 volumes/attachments - sudo chown -R 33:33 volumes/config - sudo chown -R 33:33 volumes/qgs-resources - sudo chown -R 33:33 volumes/qwc2/assets - - sudo chown 8983:8983 volumes/solr/data - -### Run containers - -Start all containers: - - docker-compose up -d - -Follow log output: - - docker-compose logs -f - -Open map viewer: - - http://localhost:8088/ - -Open Admin GUI (Admin user: `admin:admin`, requires password change on first login): - - http://localhost:8088/qwc_admin - -Sign in (Demo user: `demo:demo`): - - http://localhost:8088/auth/login - -Sign out: - - http://localhost:8088/auth/logout - -Stop all containers: - - docker-compose down - -### Add a QGIS project - -Setup PostgreSQL connection service file `~/.pg_service.conf` -for DB connections from the host machine to PostGIS container: - -``` -cat >>~/.pg_service.conf </adminGuiConfig.json` - -Example: -```json -{ - "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-admin-gui/master/schemas/qwc-admin-gui.json", - "service": "admin-gui", - "config": { - "db_url": "postgresql:///?service=qwc_configdb", - "config_generator_service_url": "http://qwc-config-service:9090", - "totp_enabled": false, - "user_info_fields": [], - "proxy_url_whitelist": [], - "proxy_timeout": 60 - } -} -``` - -To connect with the demo database, the following `~/.pg_service.conf` entry is expected: - -``` -host=localhost -port=5439 -dbname=qwc_demo -user=qwc_admin -password=qwc_admin -sslmode=disable -``` - -Set the `GROUP_REGISTRATION_ENABLED` environment variable to `False` to disable registrable groups and group registration requests, if not using the [Registration GUI](https://github.com/qwc-services/qwc-registration-gui) (default: `True`). - -To automatically logout from the admin gui after a period of inactivity, set the `IDLE_TIMEOUT` environment variable to the desired period, in seconds (default: `0`, i.e. disabled). - -Set `totp_enabled` to `true` to show the TOTP fields in the user form, if two factor authentication is enabled in the [DB-Auth service](https://github.com/qwc-services/qwc-db-auth) (default: `false`). - -### Additional user fields - -Additional user fields are saved in the table `qwc_config.user_infos` with a a one-to-one relation to `qwc_config.users` via the `user_id` foreign key. -To add custom user fields, add new columns to your `qwc_config.user_infos` table and set your `user_info_fields` to a JSON with the following structure: - -```json - { - "title": "", - "name": "", - "type": "", - "required" "" - } -] -``` - -These fields are then added to the user form. - -Example: - -```sql --- add custom columns -ALTER TABLE qwc_config.user_infos ADD COLUMN surname character varying NOT NULL; -ALTER TABLE qwc_config.user_infos ADD COLUMN first_name character varying NOT NULL; -``` - -```bash -# set user info fields config -"user_info_fields": [{"title": "Surname", "name": "surname", "type": "text", "required": true}, {"title": "First name", "name": "first_name", "type": "text", "required": true}] -``` - -### Mailer - -* `MAIL_SERVER`: default ‘localhost’ -* `MAIL_PORT`: default 25 -* `MAIL_USE_TLS`: default False -* `MAIL_USE_SSL`: default False -* `MAIL_DEBUG`: default app.debug -* `MAIL_USERNAME`: default None -* `MAIL_PASSWORD`: default None -* `MAIL_DEFAULT_SENDER`: default None -* `MAIL_MAX_EMAILS`: default None -* `MAIL_SUPPRESS_SEND`: default app.testing -* `MAIL_ASCII_ATTACHMENTS`: default False - -In addition the standard Flask `TESTING` configuration option is used by Flask-Mail in unit tests. - -### Proxy to internal services - -The route `/proxy?url=http://example.com/path?a=1` serves as a proxy for calling whitelisted internal services. This can be used e.g. to call other internal services from custom pages in the Admin GUI, without having to expose those services externally. - -Set `proxy_url_whitelist` to a list of RegExes for whitelisted URLs (default: `[]`), e.g. -```json - ["", "^http://example.com/path\\?.*$"] -``` - -Set `proxy_timeout` to the timeout in seconds for proxy requests (default: `60`s). - -### Translations - -Translation strings are stored in a JSON file for each locale in `translations/.json` (e.g. `en.json`). Add any new languages as new JSON files. - -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`. - -Usage ------ - -Base URL: - - http://localhost:5031/ - -### Default login - -username: admin -password: admin - - -Docker usage ------------- - -To run this docker image you will need a configuration database. For testing purposes you can use the demo DB. - -The following steps explain how to download the demo DB docker image and how to run the `qwc-admin-gui` service with `docker-compose`. - -**Step 1: Clone qwc-docker** - - git clone https://github.com/qwc-services/qwc-docker - cd qwc-docker - -**Step 2: Create docker-compose.yml file** - - cp docker-compose-example.yml docker-compose.yml - -**Step 3: Set flask debug mode to true** - -For the QWC Admin GUI to work without login you will have to add the following `env` variable: - - FLASK_DEBUG=1 - -**Step 4: Start docker containers** - - docker-compose up qwc-admin-gui - -For more information please visit: https://github.com/qwc-services/qwc-docker - -Development ------------ - -Create a virtual environment: - - virtualenv --python=/usr/bin/python3 .venv - -Activate virtual environment: - - source .venv/bin/activate - -Install requirements: - - pip install -r requirements.txt - -Set the `CONFIG_PATH` environment variable to the path containing the service config and permission files when starting this service (default: `config`). - - export CONFIG_PATH=../qwc-docker/volumes/config - -Configure environment: - - echo FLASK_ENV=development >.flaskenv - -Start local service: - - python server.py diff --git a/content/setup/services/qwc-config-generator.md b/content/setup/services/qwc-config-generator.md deleted file mode 100644 index 460620e4..00000000 --- a/content/setup/services/qwc-config-generator.md +++ /dev/null @@ -1,364 +0,0 @@ -+++ -menuTitle = "qwc-config-generator" -weight = 14 -chapter = false -+++ - -QWC ConfigGenerator -==================== - -Generates JSON files for service configs and permissions from WMS GetCapabilities, QGS projects and QWC ConfigDB. - - -Setup ------ - -Create a ConfigGenerator config file `tenantConfig.json` for each tenant (see below). - - -Configuration -------------- - -Example `tenantConfig.json`: -```json -{ - "$schema": "https://github.com/qwc-services/qwc-config-generator/raw/master/schemas/qwc-config-generator.json", - "service": "config-generator", - "config": { - "tenant": "default", - "config_db_url": "postgresql:///?service=qwc_configdb", - "default_qgis_server_url": "http://localhost:8001/ows/", - "qgis_projects_base_dir": "/data", - "qgis_projects_scan_base_dir": "/data/scan", - "qgis_projects_gen_base_dir": "/data/gen", - "permissions_default_allow": 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], - "defaultPrintGrid": [{"s": 10000000, "x": 1000000, "y": 1000000}, {"s": 1000000, "x": 100000, "y": 100000}, {"s": 100000, "x": 10000, "y": 10000}, {"s": 10000, "x": 1000, "y": 1000}, {"s": 1000, "x": 100, "y": 100}, {"s": 100, "x": 10, "y": 10}], - "defaultWMSVersion":"1.3.0", - "defaultBackgroundLayers": [], - "defaultSearchProviders": ["coordinates"], - "defaultMapCrs": "EPSG:3857", - "themes": { - "items": [ - { - "title": "Demo", - "url": "/ows/qwc_demo", - "default": true, - "attribution": "Demo attribution", - "attributionUrl": "https://127.0.0.1/", - "backgroundLayers": [ - { - "name": "bluemarble", - "printLayer": "bluemarble_bg", - "visibility": true - }, - { - "name": "mapnik", - "printLayer": "osm_bg" - } - ], - "searchProviders": ["coordinates"], - "mapCrs": "EPSG:3857", - "additionalMouseCrs": [], - "extent": [-1000000, 4000000, 3000000, 8000000], - "skipEmptyFeatureAttributes": true, - "printResolutions": [300], - "thumbnail": "default.jpg" - } - ], - "backgroundLayers": [ - { - "name": "mapnik", - "title": "Open Street Map", - "type": "osm", - "source": "osm", - "thumbnail": "mapnik.jpg", - "attribution": "OpenStreetMap contributors", - "attributionUrl": "https://www.openstreetmap.org/copyright" - } - ] - } - }, - "custom_resource_types": [], - "services": [ - { - "name": "ogc", - "generator_config": { - "wms_services": { - "online_resources": { - "service": "http://localhost:8088/ows/", - "feature_info": "http://localhost:8088/ows/", - "legend": "http://localhost:8088/ows/" - } - } - }, - "config": { - "default_qgis_server_url": "http://qwc-qgis-server/ows/" - } - }, - { - "name": "mapViewer", - "generator_config": { - "qwc2_config": { - "qwc2_config_file": "../qwc-docker/volumes/qwc2/config.json", - "qwc2_index_file": "../qwc-docker/volumes/qwc2/index.html" - } - }, - "config": { - "qwc2_path": "/qwc2/", - "auth_service_url": "/auth/", - "data_service_url": "/api/v1/data/", - "#document_service_url": "/api/v1/document/", - "elevation_service_url": "/elevation/", - "#info_service_url": "/api/v1/featureinfo/", - "#legend_service_url": "/api/v1/legend/", - "mapinfo_service_url": "/api/v1/mapinfo/", - "ogc_service_url": "/ows/", - "permalink_service_url": "/api/v1/permalink/", - "#print_service_url": "/api/v1/print/", - "search_data_service_url": "/api/v1/data/", - "search_service_url": "/api/v2/search/" - } - }, - { - "name": "featureInfo", - "config": { - "default_qgis_server_url": "http://qwc-qgis-server/ows/" - } - }, - { - "name": "search", - "config": { - "solr_service_url": "http://qwc-solr:8983/solr/gdi/select", - "search_result_limit": 50, - "db_url": "postgresql:///?service=qwc_geodb" - }, - "resources": { - "facets": [ - { - "name": "background", - "filter_word": "Background" - }, - { - "name": "foreground", - "filter_word": "Map" - }, - { - "name": "ne_10m_admin_0_countries", - "filter_word": "Country", - "table_name": "qwc_geodb.search_v", - "geometry_column": "geom", - "facet_column": "subclass" - } - ] - }, - "permissions": [ - { - "role": "public", - "permissions": { - "dataproducts": [ - "qwc_demo" - ], - "solr_facets": [ - "foreground", - "ne_10m_admin_0_countries" - ] - } - } - ] - } - ] -} -``` - -For a full example see [tenantConfig-example.json](tenantConfig-example.json) ([JSON schema](schemas/qwc-config-generator.json)). - -*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. -In order to have projects automatically added, the following settings need to be defined in `themesConfig`. - -- `defaultBackgroundLayers` -- `defaultSearchProviders` -- `defaultMapCrs` - -The ConfigGenerator can also autodetect thumbnails when adding projects. The projects have to meet the following criteria: - -- `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 - -*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 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 - { - "name": "featureInfo", - "config": { - "default_qgis_server_url": "http://qwc-qgis-server/ows/" - }, - "resources": { - "wms_services": [ - { - "name": "external_info_layers", - "root_layer": { - "name": "external_info_layers", - "layers": [ - { - "name": "example_info_layer", - "title": "External info layer", - "attributes": [ - { - "name": "name" - }, - { - "name": "geometry" - } - ], - "info_template": { - "type": "wms", - "wms_url": "https://example.com/wms/demo" - } - } - ] - } - } - ] - }, - "permissions": [ - { - "role": "public", - "permissions": { - "wms_services": [ - { - "name": "external_info_layers", - "layers": [ - { - "name": "external_info_layers" - }, - { - "name": "example_info_layer", - "attributes": ["name", "geometry"], - "info_template": true - } - ] - } - ] - } - } - ] - } -``` - - -### 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 `//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` and not `qwc-config-generator:v-noqgis`. - -### Schema validation - -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 - -Using the `permissions_default_allow` setting, some resources can be set to be permitted or restricted by default if no permissions are set (default: `true`). Affected resources are `map`, `layer`, `print_template` and `viewer_task`. - -* i.e. `permissions_default_allow: true`: all maps, layers and attributes are permitted by default -* i.e. `permissions_default_allow: false`: maps and layers are only available if their resources and permissions are explicitly configured; though attributes are still permitted by default - -### Custom resource types - -If you want to define custom resource types for a custom service, you can add a record for the resource type to the configdb - - INSERT INTO qwc_config.resource_types(name, description, list_order) values ('', '', ); - -and then add it to the `custom_resource_types` setting. - - -Usage ------ - -### Script - -Show command options: - - python config_generator_cli.py --help - -Generate both service configs and permissions: - - python config_generator_cli.py ./tenantConfig.json all - -Generate service config files: - - python config_generator_cli.py ./tenantConfig.json service_configs - -Generate permissions file: - - python config_generator_cli.py ./tenantConfig.json permissions - -### Service - -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:* the ConfigGenerator's docker user (`www-data`) needs to have write permissions to the directory defined in `OUTPUT_CONFIG_PATH`! - -Base URL: - - http://localhost:5010/ - -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 ------------ - -Create a virtual environment: - - virtualenv --python=/usr/bin/python3 --system-site-package .venv - -Activate virtual environment: - - source .venv/bin/activate - -Install requirements (*NOTE:* additionally requires modules from `python-qgis`): - - pip install -r requirements.txt - -Run Demo-DB and QGIS Server: - - cd ../qwc-docker && docker-compose up -d qwc-postgis qwc-qgis-server - -Generate service configs and permissions for Docker: - - python config_generator_cli.py ./tenantConfig-example.json all diff --git a/content/setup/services/qwc-data-service.md b/content/setup/services/qwc-data-service.md deleted file mode 100644 index 8532a8eb..00000000 --- a/content/setup/services/qwc-data-service.md +++ /dev/null @@ -1,387 +0,0 @@ -+++ -menuTitle = "qwc-data-service" -weight = 9 -chapter = false -+++ - -QWC Data Service -================ - -Edit spatial and unlocated features of datasets via GeoJSON. - -**Note:** requires a PostGIS database for reading and writing features - -Setup ------ - -Uses PostgreSQL connection service or connection to a PostGIS database. -This connection's user requires read and write access to the configured tables. - -### qwc_demo example - -Uses PostgreSQL connection service `qwc_geodb` (GeoDB). -The user `qwc_service_write` requires read and write access to the configured tables -of the data layers from the QGIS project `qwc_demo.qgs`. - -Setup PostgreSQL connection service file `~/.pg_service.conf`: - -``` -host=localhost -port=5439 -dbname=qwc_demo -user=qwc_service_write -password=qwc_service_write -sslmode=disable -``` - - -Configuration -------------- - -The static config and permission files are stored as JSON files in `$CONFIG_PATH` with subdirectories for each tenant, -e.g. `$CONFIG_PATH/default/*.json`. The default tenant name is `default`. - - -### Data Service config - -* [JSON schema](schemas/qwc-data-service.json) -* File location: `$CONFIG_PATH//dataConfig.json` - -Example: -```json -{ - "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-data-service/v2/schemas/qwc-data-service.json", - "service": "data", - "config": { - "attachments_base_dir": "/tmp/qwc_attachments/", - "allowed_attachment_extensions": ".bmp,.jpg,.pdf", - "max_attachment_file_size": 10485760, - "upload_user_field_suffix": "uploaduser", - "edit_user_field": "edituser", - "edit_timestamp_field": "edittimestamp" - }, - "resources": { - "datasets": [ - { - "name": "qwc_demo.edit_points", - "db_url": "postgresql:///?service=qwc_geodb", - "schema": "qwc_geodb", - "table_name": "edit_points", - "primary_key": "id", - "fields": [ - { - "name": "id", - "data_type": "integer", - "constraints": { - "min": -2147483648, - "max": 2147483647 - } - }, - { - "name": "name", - "data_type": "character varying", - "constraints": { - "maxlength": 32 - } - }, - { - "name": "description", - "data_type": "text" - }, - { - "name": "num", - "data_type": "integer", - "constraints": { - "min": -2147483648, - "max": 2147483647 - } - }, - { - "name": "value", - "data_type": "double precision", - "constraints": { - "pattern": "[0-9]+([\\.,][0-9]+)?" - } - }, - { - "name": "type", - "data_type": "smallint", - "constraints": { - "min": -32768, - "max": 32767 - } - }, - { - "name": "amount", - "data_type": "numeric", - "constraints": { - "numeric_precision": 5, - "numeric_scale": 2, - "min": -999.99, - "max": 999.99, - "step": 0.01 - } - }, - { - "name": "validated", - "data_type": "boolean" - }, - { - "name": "datetime", - "data_type": "timestamp without time zone" - } - ], - "geometry": { - "geometry_column": "geom", - "geometry_type": "POINT", - "srid": 3857 - } - } - ] - } -} -``` - -### Permissions - -* [JSON schema](https://github.com/qwc-services/qwc-services-core/blob/master/schemas/qwc-services-permissions.json) -* File location: `$CONFIG_PATH//permissions.json` - -Example: -```json -{ - "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-services-core/master/schemas/qwc-services-permissions.json", - "users": [ - { - "name": "demo", - "groups": ["demo"], - "roles": [] - } - ], - "groups": [ - { - "name": "demo", - "roles": ["demo"] - } - ], - "roles": [ - { - "role": "public", - "permissions": { - "data_datasets": [ - { - "name": "qwc_demo.edit_points", - "attributes": [ - "id", - "name", - "description", - "num", - "value", - "type", - "amount", - "validated", - "datetime" - ], - "writable": true, - "creatable": true, - "readable": true, - "updatable": true, - "deletable": true - } - ] - } - } - ] -} -``` - -### Overview - - QWC2 build: Public: - +--------------------+ +------------+ - | themesConfig.json | | | - | ^ +-----------> yarn build +----------------------------------> (themes.json) - | | | +---> | - | + +-----+ | +------------+ +---------------+ - | (edit.json) | | | | | - +--------------------+ | +------------------------+ QGIS Server +----------> WMS/WFS - | | Capabilities | | - +--------------------+ | | +------^--------+ - | ui Files +-----------------------------------------------------------> assets/*.ui - +--------------------+ | | | - | | | +------------------+ - +--------------------+ | | + | +--> html/js/css/assets - | qgs Files +--+-------------------------------> *.qgs +---------> qwc-map-viewer | - +--------------------+ | | | | | +--> config.json/themes.json - | | | | +------------------+ - | | | | - | | | | +------------------+ - | | | | | | REST-API - +---------+ | | | +---------> qwc-data-service <---------------> - | | | | | +------------+ | | | - | config- | | | +---> | + +------------------+ - | DB | +-------v--v-----> Config- +------> [service].json+permissions.json - | | | Generator | - | | | | - +---------+ +------------+ - -Edit forms: - -- Edit forms are automatically created from field information extracted from QGS files, according to the attribute form configuration: - * For autogenerated attribute forms, a flat edit form is in QWC2 - * Drag and Drop designer forms are automatically translated to Qt Designer forms in the `assets/forms/autogen` and loaded by QWC2 - * UI file are copied to the `assets/forms/autogen` folder and loaded by QWC2 - -- You can also manually create Qt Designer forms to use exclusively with QWC2 as follows: - * For the desired theme, add a block as follows in the theme block of the `tenantConfig.json`: - - "editConfig":{ - "":{ - "editDataset":".", - "layerName":"", - "geomType":"", - "form":":/forms/form.ui" - } - } - - Note: `:/` in the `form` property is resolved to the assets directory of the viewer. - * Create the designer form in Qt-Designer, using the dataset field names as edit widget names. -- *Note*: In general, for tables with an auto-incrementing primary key field, you'll want to set the attribute form widget type to "Hidden" in the QGIS layer properties. This way, the data-service won't block the commit if the feature is comitted with an empty PK field value. - -- Starting with qwc-map-viewer v2022.05.17, localized translation forms are supported. To this end, place a Qt Translation file called `_.ts` next to the designer form `.ui`, where `lang` is a language or language/country code, i.e. `en` or `en-US`. There is a [`translateui.sh`](https://github.com/qgis/qwc2/tree/master/scripts/translateui.sh) script to help generate the translation files. Example: - - ./translateui.sh <...>/qwc2/assets/forms/form.ui de it fr - - -File uploads: - -- For Autogenerated and Drag and Drop designer forms, set the widget type to Attachment. You can set the file type filter in the widget configuration under `Display button to open file dialog -> Filter`. -- For manually created Qt Designed Ui forms, use a `QLineEdit` widget named `__upload`, and optionally as the text value of the `QLineEdit` set a comma separated list of suggested file extensions. -- *Note*: Make sure the client uses the EditingInterface.js shipped with [QWC2 submodule f053fdc or newer](https://github.com/qgis/qwc2/commit/f053fdceba4a2d8112fb516c793702b9fd118609) to support file uploads. -- You can set the allowed attachment extensions and maximum file sizes globally by setting `allowed_attachment_extensions` and `max_attachment_file_size` in the data service configuration. -- You can also set the allowed attachment extensions and maximum file sizes per dataset by setting `max_attachment_file_size_per_dataset` and `allowed_extensions_per_dataset` in the dataset service configuration. If you set the per dataset values, the global settings will be disregarded (i.e. if a attachment satisfies the per dataset constraint it will be considered valid, even if it violates the global constraint). - -Logging mutations: - -- If you set `upload_user_field_suffix` in the data service config, the username of the last user who performed a mutation to `` will be logged to `__`. -- If you set `edit_user_field` in the data service config, the username of the last user who performed a mutation to a record with be logged to the `` field of the record. -- If you set `edit_timestamp_field` in the data service config, the timestamp of the last mutation to a record will be logged to the `` field of the record. - -Note: for these fields to be written, ensure the qgis project is also up-to-date, i.e. that contain the up-to-date table schemas. You can set the respective field types to hidden in the QGIS layer properties to avoid them showing up in the autogenerated edit forms. - -1:N relations: - -- For autogenerated and Drag and Drop designer forms, configure the 1-N relation in the QGIS project properties. -- In a manually created Qt-Designer Ui form, create a widget of type `QWidget`, `QGroupBox` or `QFrame` named according to the pattern `nrel____`, where `` is the name of the relation table and `` the name of the foreign key field in the relation table. -- In a manually created Qt-Designer Ui form, you can also specify a sort column for the 1:N relation in the form `nrel______`. If a sort-column is specified, QWC2 will display sort arrows for each entry in the relation widget. -- Inside this widget, add the edit widgets for the values of the relation table. Name the widgets `__`. These edit widgets will be replicated for each relation record. -- *Note:* The relation table needs to be added as a (geometryless) table to the QGIS Project. You also need to set appropriate permissions for the relation table dataset in the QWC admin backend. - -Key-value relations: - -- For Drag and Drop designer forms, use widgets of type Value Relation. In the generated designer form, the naming convention indicated below is used. -- In a manually created Qt-Designer Ui form, you can use key-value relations for combo box entries by naming the `QComboBox` widget according to the following pattern: `kvrel________`. `` refers to a table containing a field called `` for the value of the entry and a field `` for the label of the entry. For key-value relations inside a 1:N relation, use `kvrel__________`. `` -- *Note:* In any case, the relation table needs to be added as a (geometryless) table to the QGIS Project. You also need to set appropriate permissions for the relation table dataset in the QWC admin backend. Alternatively, you can set `"autogen_keyvaltable_datasets": true` in the config generator configuration, to automatically generate resources and read-only permissions as required. - -Special form widgets: - -- In manually created Qt-Designer Ui forms, there are a number of special widgets you can define: - - * *Images*: To display attribute values which contain an image URL as an inline image, use a `QLabel` named `img__`. - * *Linked features*: To display a button to choose a linked feature and edit it's attributes in a nested edit form, create a `QPushButton` named `featurelink____` (simple join) or `featurelink______` in a 1:N relation. In a 1:N relation, `linkdataset` can be equal to `reltable` to edit the relation record itself in the nested form. `fieldname` will contain the `id` of the linked feature. - * *External fields*: Some times it is useful to display information from an external source in the edit form. This can be accomplished by creating a `QWidget` with name `ext__` and using a form preprocessor hook (see `registerFormPreprocessor` in [`QtDesignerForm.jsx`](https://github.com/qgis/qwc2/blob/master/components/QtDesignerForm.jsx) to populate the field by assigning a React fragment to `formData.externalFields.`. - * *Buttons*: To add a button with a custom action, add a `QPushButton` with name `btn__`, and use a form preprocessor hook to set the custom function to `formData.buttons.buttonname.onClick`. - -Data service configuration: - -- DB connection information, table and column names and primary key information are extracted from QGS files -- Data contraints are extracted from QGS files -- Column types and additional constraints are read from the the geo-DB - -Data read/write: - -- QWC2 issues data-service API requests for reading und writing - - -Usage ------ - -Set the `CONFIG_PATH` environment variable to the path containing the service config and permission files when starting this service (default: `config`). - -Base URL: - - http://localhost:5012/ - -Service API: - - http://localhost:5012/api/ - -Sample requests: - - curl 'http://localhost:5012/qwc_demo.edit_points/' - - -Docker usage ------------- - -To run this docker image you will need a PostGIS database. For testing purposes you can use the demo DB. - -The following steps explain how to download the demo DB docker image and how to run the `qwc-data-service` with `docker-compose`. - -**Step 1: Clone qwc-docker** - - git clone https://github.com/qwc-services/qwc-docker - cd qwc-docker - -**Step 2: Create docker-compose.yml file** - - cp docker-compose-example.yml docker-compose.yml - -**Step 3: Start docker containers** - - docker-compose up qwc-data-service - -For more information please visit: https://github.com/qwc-services/qwc-docker - -Development ------------ - -Create a virtual environment: - - virtualenv --python=/usr/bin/python3 --system-site-packages .venv - -Without system packages: - - virtualenv --python=/usr/bin/python3 .venv - -Activate virtual environment: - - source .venv/bin/activate - -Install requirements: - - pip install -r requirements.txt - -Start local service: - - CONFIG_PATH=/PATH/TO/CONFIGS/ python server.py - - -Testing -------- - -Run all tests: - - python test.py - -Run single test module: - - python -m unittest tests.feature_validation_tests - -Run single test case: - - python -m unittest tests.feature_validation_tests.FeatureValidationTestCase - -Run single test method: - - python -m unittest tests.feature_validation_tests.FeatureValidationTestCase.test_field_constraints diff --git a/content/setup/services/qwc-document-service.md b/content/setup/services/qwc-document-service.md deleted file mode 100644 index f8f6d09d..00000000 --- a/content/setup/services/qwc-document-service.md +++ /dev/null @@ -1,136 +0,0 @@ -+++ -menuTitle = "qwc-document-service" -weight = 10 -chapter = false -+++ - -Document service -================ - -The document service delivers reports from the Jasper reporting service with permission control. - - -Dependencies ------------- - -* [Jasper reporting service](https://github.com/qwc-services/jasper-reporting-service/) - - -Configuration -------------- - -The static config files are stored as JSON files in `$CONFIG_PATH` with subdirectories for each tenant, -e.g. `$CONFIG_PATH/default/*.json`. The default tenant name is `default`. - -### JSON config - -* [JSON schema](schemas/qwc-document-service.json) -* File location: `$CONFIG_PATH//documentConfig.json` - -Example: -```json -{ - "$schema": "https://raw.githubusercontent.com/qwc-services/qwc-document-service/master/schemas/qwc-document-service.json", - "service": "document", - "config": { - "jasper_service_url": "http://localhost:8002/reports", - "jasper_timeout": 60 - }, - "resources": { - "document_templates": [ - { - "template": "demo", - "report_filename": "PieChartReport" - } - ] - } -} -``` - -### Environment variables - -Config options in the config file can be overridden by equivalent uppercase environment variables. - -Environment variables: - -| Variable | Description | Default value | -|----------------------|----------------------------|-------------------------------| -| `JASPER_SERVICE_URL` | Jasper Reports service URL | http://localhost:8002/reports | -| `JASPER_TIMEOUT` | Timeout (s) | 60 | - - -Usage ------ - -API documentation: - - http://localhost:5018/api/ - -Request format: - - http://localhost:5018/