QWC Services configuration

The architecture of qwc-services is as follows:

QWC Services Arch

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:

REST services:

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 of volumes/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 in volumes/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.