QWC Services configuration¶
The architecture of qwc-services
is as follows:
- API-Gateway: API Gateway, forwards requests to individual services http://localhost:8088
- Auth-Service: Authentication service with local user database (default users: admin:admin, demo:demo) http://localhost:8088/auth/login
- Map viewer: QWC2 map viewer http://localhost:8088
- OGC Service: Proxy for WMS/WFS requests filtered by permissions, calls QGIS Server http://localhost:8088/ows/api
- Admin GUI: Admin GUI http://localhost:8088/qwc_admin/
qwc-docker
ships a pre-configured the qwc-services
ecosystem as an easy to use application.
Service overview¶
Following is an overview of existing qwc-services
:
Applications:
- QWC2 Map Viewer: The map viewer application
- QWC Admin GUI: Configuration backend for managing users and permissions
- Registration GUI: GUI for registration of new users
REST services:
- DB auth service: Authentication service with local user database
- LDAP auth service: LDAP Authentication service
- Data service: Data edit service, required for QWC2 editing functionality
- Document service: Service for generating Jasper reports
- Elevation service: Service for providing elevation data, required for QWC2 elevation profile
- Feature info service: Service for providing enhanced GetFeatureInfo responses to QWC2
- Fulltext search service: Fulltext search service for the QWC2 search functionality
- Legend service: Service for providing enhanced legend graphics to QWC2
- Mapinfo service: Service for providing additional information to the QWC2 right-click map context popup
- OGC service: Proxy for WMS/WFS requests filtered by permissions, calls QGIS Server
- Permalink service: Service for storing compat permalinks and bookmarks generated by QWC2
- Print service: Service for enhancing the QWC2 GetPrint requests
Configuration database:
Configuration generator:
qwc-docker
layout¶
The layout of the qwc-docker
tree is as follows:
Path | Description |
---|---|
├─ api-gateway/nginx.conf |
API gateway configuration. |
├─ volumes/ |
Contains folders which are mounted into the various containers. |
│ ├─ attachments |
Storage of files uploaded through the QWC2 editing functionality. |
│ ├─ config/<tenant>/ |
Service configuration files, generated by qwc-config-generator . |
│ ├─ config-in/<tenant>/ |
Input configuration files, processed by the qwc-config-generator . |
│ │ ├─ config.json |
Master configuration for the QWC2 viewer. |
│ │ ├─ index.html |
Viewer entry point. |
│ │ ├─ themesConfig.json |
Themes configuration. |
│ │ └─ tenantConfig.json |
Master configuration file for qwc services. |
│ ├─ db/ |
Storage of configuration database (see Config DB). |
│ ├─ info-templates/ |
Custom feature-info templates (see qwc-feature-info-service ). |
│ ├─ jasper-reports/ |
Jasper reports (see qwc-document-service ). |
│ ├─ legends/ |
Custom legend images (see qwc-legend-service ). |
│ ├─ qgs-resources/ |
QGIS projects and data referenced by the projects. |
│ ├─ qwc2/ |
QWC2 Viewer. |
│ └─ solr/ |
Fulltext search index. |
├─ docker-compose.yml |
Container configuration file. |
├─ pg_service.conf |
Database service definitions. |
└─ pg_service-write.conf |
Database service definitions for write connections. |
Service configurations¶
The master configuration file for the QWC services is located at qwc-docker/volumes/config-in/<tenant>/tenantConfig.json
, where <tenant>
is the tenant name, default
by default. See Multi Tenancy for more details on tenants.
The file is structured as follows:
{
"$schema": "https://github.com/qwc-services/qwc-config-generator/raw/master/schemas/qwc-config-generator.json",
"service": "config-generator",
"config": {
<ConfigGenerator config>
},
"themesConfig": "./themesConfig.json",
"services": [
{
"name": "<service name",
<Service config>
},
...
]
}
Refer to the qwc-config-generator
schema for the available ConfigGenerator config
settings.
themesConfig
is a relative path to the theme configuration file as documented in Theme configuration.
Theservices
block contains the configuration for the individual QWC services, as documented in the reference.
Note: All config settings can also be set as environment variables in capitalized form in docker-compose.yml
.
Note: Some variables must be set as environment variables in docker-compose.yml
:
ENV | Default value | Description |
---|---|---|
INPUT_CONFIG_PATH |
config-in |
Base path for service configuration files |
OUTPUT_CONFIG_PATH |
/tmp |
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 |
Enabling additional services¶
- Add service entry in
qwc-services/docker-compose.yml
, setting the service mountpoint:
SERVICE_MOUNTPOINT=/<mountpoint>
Example:
qwc-print-service:
image: sourcepole/qwc-print-service:vYYYY.MM.DD
environment:
<<: *qwc-service-variables
SERVICE_MOUNTPOINT: '/api/v1/print'
volumes:
- ./volumes/config:/srv/qwc_service/config:ro
ports:
- "127.0.0.1:5020:9090"
- Add corresponding entry in
api-gateway/nginx.conf
, example:
location /api/v1/print {
proxy_pass http://qwc-print-service:9090;
}
- If necessary, uncomment/add the respective service url (see also the qwc-map-viewer schema reference) in the
mapViewer
config block ofvolumes/config-in/default/tenantConfig.json
, i.e.
{
"name": "mapViewer",
"generator_config": {
# ...
},
"config": {
"print_service_url": "/api/v1/print/",
# ...
}
}
- Add the service configuration block below
services
involumes/config-in/default/tenantConfig.json
, according to the service config schema, i.e.
{
"name": "print",
"config": {
"ogc_service_url": "http://qwc-ogc-service:9090/",
"qgis_server_version": "3.16"
}
}
Configuration database¶
The Configuration database (CofigDB) 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 qwc-docker/pg_service.conf
.
To use an external configuration database, either change the connection definition for qwc_configdb
in qwc-docker/pg_service.conf
or change the config_db_url
in qwc-docker/volumes/config-in/<tenant>/tenantConfig.json
.
Database migrations¶
Migrations to the ConfigDB are applied automatically by the qwc-base-db-migrate
image which is included in the sample docker-compose-example.yml
.
To upgrade the ConfigDB to a newer version, it is sufficient to change the version of the image to the desired version, and migrations will be applied automatically next time the application is restarted.
See the qwc-base-db
README for more info.
Keeping QWC services up to date¶
When using qwc-docker
, updating the services is a simple as updating the image tags in qwc-docker/docker-compose.yml
.
Two versioning schemes are available:
vYYYY-MM-DD
: These refer to the latest available "development" version of the respective images (i.e.v2023.05.12
).vYYYY.X-lts
: These refer to the long term support version of the respective images (i.e.v2023.1-lts
).
You can always check the available tags on dockerhub, for example at https://hub.docker.com/r/sourcepole/qwc-config-generator.
In particular, to special tags exist, latest
, latest-lts
and latest-YYYY-lts
(i.e. latest-2024-lts
) which always refer to the latest available "development" and long term support versions respectively. Note however that using these tags will result in docker automatically pulling new versions when the application is launched, which may be undesired.
The qwc-docker
Upgrade Notes documents major changes, and in particular all incompatible changes between releases which require changes to the application specific code and/or configuration.