Skip to content

Commit 2d80082

Browse files
fmigneaultfmigneault
authored
Add OGC API DGGS service + associated utility components (#583)
## Overview DGGS ([Discrete Global Grid Systems](https://ogcapi.ogc.org/dggs/)) allow returning data in other formats than the typical `(lat,lon)`, by following a predefined discrete grid to contain the data. This PR adds support of an *OGC API - DGGS* open source implementation that was augmented with Dockerized packaging. In the long run, further integration with other services is planned (notably Weaver and STAC), but this prepares only the minimal setup to have the service "running". For reference, it is running here: https://hirondelle.crim.ca/dggs-api/ API Docs: https://hirondelle.crim.ca/dggs-api/docs ## Changes **Non-breaking changes** - DGGS: Add the new `components/dggs` providing an OGC API for Discrete Global Grid Systems. - DGGS API available through `/dggs-api` path (default, configurable via `DGGS_API_PATH`). - Redirects available for `/ogcapi/dggs/...` and `/ogcapi/collections/.../dggs/...`. - Sample configuration (minimum 1 resolvable data provider required) uses the new feature of `optional-components/secure-data-proxy` on CRIM's Hirondelle server. - Data: Allow `optional-components/secure-data-proxy` to define generic and flexible locations. - `SECURE_DATA_PROXY_ROOT` can be defined as mount directory inside the `proxy` service. - `SECURE_DATA_PROXY_LOCATIONS` can be defined with any amount of custom locations. - All locations can be configured (as desired) under Magpie `secure-data-proxy` service for access control. - Other components (`wps_output-volume`, `stac-data-proxy`) that can optionally use this security middleware via `SECURE_DATA_PROXY_AUTH_INCLUDE` can still do so. Their mount points are handled separately. - Weaver: Modified `/ogcapi/...` redirections strategy via `WEAVER_ALT_PREFIX_PROXY_LOCATION`. - Allows other OGC APIs to reuse the same prefix to provide a unified location to access them. **Breaking changes** - n/a ## Related Issue / Discussion - relates to LandscapeGeoinformatics/pydggsapi#13 - relates to https://www.ogc.org/initiatives/ai-dggs-pilot/
2 parents a839d0b + b675cba commit 2d80082

File tree

26 files changed

+743
-20
lines changed

26 files changed

+743
-20
lines changed

‎.bumpversion.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[tool.bumpversion]
2-
current_version = "2.18.16"
2+
current_version = "2.19.0"
33
commit = true
44
tag = false
55
tag_name = "{new_version}"

‎CHANGES.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,27 @@
1717

1818
[//]: # (list changes here, using '-' for each new entry, remove this when items are added)
1919

20+
[2.19.0](https://github.com/bird-house/birdhouse-deploy/tree/2.19.0) (2025-12-05)
21+
------------------------------------------------------------------------------------------------------------------
22+
23+
## Changes
24+
25+
- DGGS: Add the new `components/dggs` providing an OGC API for Discrete Global Grid Systems.
26+
- DGGS API available through `/dggs-api` path (default, configurable via `DGGS_API_PATH`).
27+
- Redirects available for `/ogcapi/dggs/...` and `/ogcapi/collections/.../dggs/...`.
28+
- Sample configuration (minimum 1 resolvable data provider required) uses the new
29+
feature of `optional-components/secure-data-proxy` on CRIM's Hirondelle server.
30+
31+
- Data: Allow `optional-components/secure-data-proxy` to define generic and flexible locations.
32+
- `SECURE_DATA_PROXY_ROOT` can be defined as mount directory inside the `proxy` service.
33+
- `SECURE_DATA_PROXY_LOCATIONS` can be defined with any amount of custom locations.
34+
- All locations can be configured (as desired) under Magpie `secure-data-proxy` service for access control.
35+
- Other components (`wps_output-volume`, `stac-data-proxy`) that can optionally use this security middleware
36+
via `SECURE_DATA_PROXY_AUTH_INCLUDE` can still do so. Their mount points are handled separately.
37+
38+
- Weaver: Modified `/ogcapi/...` redirections strategy via `WEAVER_ALT_PREFIX_PROXY_LOCATION`.
39+
- Allows other OGC APIs to reuse the same prefix to provide a unified location to access them.
40+
2041
[2.18.16](https://github.com/bird-house/birdhouse-deploy/tree/2.18.16) (2025-12-05)
2142
------------------------------------------------------------------------------------------------------------------
2243

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ override BIRDHOUSE_MAKE_DIR := $(shell realpath -P $$(dirname $(BIRDHOUSE_MAKE_C
88
# Generic variables
99
override SHELL := bash
1010
override APP_NAME := birdhouse-deploy
11-
override APP_VERSION := 2.18.16
11+
override APP_VERSION := 2.19.0
1212

1313
# utility to remove comments after value of an option variable
1414
override clean_opt = $(shell echo "$(1)" | $(_SED) -r -e "s/[ '$'\t'']+$$//g")

‎README.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@ for a full-fledged production platform.
1818
* - citation
1919
- | |citation|
2020

21-
.. |commits-since| image:: https://img.shields.io/github/commits-since/bird-house/birdhouse-deploy/2.18.16.svg
21+
.. |commits-since| image:: https://img.shields.io/github/commits-since/bird-house/birdhouse-deploy/2.19.0.svg
2222
:alt: Commits since latest release
23-
:target: https://github.com/bird-house/birdhouse-deploy/compare/2.18.16...master
23+
:target: https://github.com/bird-house/birdhouse-deploy/compare/2.19.0...master
2424

25-
.. |latest-version| image:: https://img.shields.io/badge/tag-2.18.16-blue.svg?style=flat
25+
.. |latest-version| image:: https://img.shields.io/badge/tag-2.19.0-blue.svg?style=flat
2626
:alt: Latest Tag
27-
:target: https://github.com/bird-house/birdhouse-deploy/tree/2.18.16
27+
:target: https://github.com/bird-house/birdhouse-deploy/tree/2.19.0
2828

2929
.. |readthedocs| image:: https://readthedocs.org/projects/birdhouse-deploy/badge/?version=latest
3030
:alt: ReadTheDocs Build Status (latest version)

‎RELEASE.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
2.18.16 2025-12-05T19:37:01Z
1+
2.19.0 2025-12-05T19:41:43Z

‎birdhouse/components/README.rst‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -720,6 +720,7 @@ How to Enable the Component
720720
- Edit ``env.local`` (a copy of `env.local.example`_)
721721
- Add ``./components/stac`` to ``BIRDHOUSE_EXTRA_CONF_DIRS``.
722722
723+
723724
STAC Browser
724725
============
725726
@@ -750,12 +751,53 @@ For example:
750751
# you can update it to
751752
export STAC_CORS_ORIGINS='http://example.com ~http:(www|other)\.api\.example\.com https://geojson.io'
752753
754+
753755
How to Enable the Component
754756
---------------------------
755757
756758
- Edit ``env.local`` (a copy of `env.local.example`_)
757759
- Add ``./components/stac-browser`` to ``BIRDHOUSE_EXTRA_CONF_DIRS``.
758760
761+
762+
.. _components_dggs:
763+
764+
DGGS: Discrete Global Grid Systems API
765+
======================================
766+
767+
`DGGS`_ is a spatial reference system combining a discrete global grid hierarchy with a zone identifier, in contrast
768+
to typical ``(lat, lon)`` spatial reference systems. By using a predefined and deterministic order of zone IDs and
769+
refinement sub-zones, DGGS enables efficient access, representation and analysis of spatial data that has been
770+
quantized over a certain grid reference system (DGGRS).
771+
772+
The *OGC API - DGGS* definition implemented by this service is a RESTful API that provides access to DGGS resources,
773+
definitions, zonal query conversion, and data retrieval from precomputed datasets.
774+
775+
.. _DGGS: https://ogcapi.ogc.org/dggs/
776+
777+
Usage
778+
-----
779+
780+
Once enabled, the API will be accessible (by default) on the ``/dggs-api`` endpoint.
781+
It will also be available through the common ``/ogcapi/dggs`` alias.
782+
783+
Refer to the `DGGS`_ OGC API documentation for specific endpoints and features.
784+
785+
Refer to `vgrid DGGS <https://github.com/opengeoshub#vgrid-dggs>`_ and
786+
the `vgrid repository <https://github.com/opengeoshub/vgrid>`_ for a relatively extensive
787+
collection of DGGS tools and its associated data manipulation ecosystem (using ``xarray``, QGIS plugin, etc.).
788+
789+
How to Enable the Component
790+
---------------------------
791+
792+
- Edit ``env.local`` (a copy of `env.local.example`_)
793+
- Add ``./components/dggs`` to ``BIRDHOUSE_EXTRA_CONF_DIRS``.
794+
- Define ``DGGS_CONFIG_PATH`` in the ``env.local`` with custom definitions.
795+
Alternatively, employ sample DGGS dataset and configuration by enabling ``./optional-components/dggs-data-sample``.
796+
Enabling this optional component will set ``DGGS_CONFIG_PATH`` with a predefined configuration for this sample data.
797+
See the `PyDGGS-API implementation <https://github.com/LandscapeGeoinformatics/pydggsapi>`_ for more details.
798+
- Optionally, configure variables in ``./components/dggs/default.env`` via ``env.local`` to customize the service.
799+
800+
759801
Canarie-API
760802
===========
761803
@@ -988,10 +1030,11 @@ of all processes executed by these services.
9881030
Usage
9891031
-----
9901032
991-
All outputs from these processes will become available at the ``${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/wpsoutputs`` endpoint.
1033+
All outputs from these processes will become available at
1034+
the ``${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/wpsoutputs`` endpoint.
9921035
9931036
By default, this endpoint is not protected. To secure access to this endpoint it is highly recommended to enable the
994-
`./optional-components/secure-data-proxy` component as well.
1037+
``./optional-components/secure-data-proxy`` component as well.
9951038
9961039
How to Enable the Component
9971040
---------------------------

‎birdhouse/components/canarie-api/docker_configuration.py.template‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -108,8 +108,8 @@ SERVICES = {
108108
# NOTE:
109109
# Below version and release time auto-managed by 'make VERSION=x.y.z bump'.
110110
# Do NOT modify it manually. See 'Tagging policy' in 'birdhouse/README.rst'.
111-
'version': '2.18.16',
112-
'releaseTime': '2025-12-05T19:37:01Z',
111+
'version': '2.19.0',
112+
'releaseTime': '2025-12-05T19:41:43Z',
113113
'institution': '${BIRDHOUSE_INSTITUTION}',
114114
'researchSubject': '${BIRDHOUSE_SUBJECT}',
115115
'supportEmail': '${BIRDHOUSE_SUPPORT_EMAIL}',
@@ -141,8 +141,8 @@ PLATFORMS = {
141141
# NOTE:
142142
# Below version and release time auto-managed by 'make VERSION=x.y.z bump'.
143143
# Do NOT modify it manually. See 'Tagging policy' in 'birdhouse/README.rst'.
144-
'version': '2.18.16',
145-
'releaseTime': '2025-12-05T19:37:01Z',
144+
'version': '2.19.0',
145+
'releaseTime': '2025-12-05T19:41:43Z',
146146
'institution': '${BIRDHOUSE_INSTITUTION}',
147147
'researchSubject': '${BIRDHOUSE_SUBJECT}',
148148
'supportEmail': '${BIRDHOUSE_SUPPORT_EMAIL}',

‎birdhouse/components/dggs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
config/magpie/config.yml
2+
config/proxy/conf.extra-service.d/dggs.conf
3+
service-config.json

‎birdhouse/components/dggs/config/magpie/config.yml.template‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
providers:
2+
# definition of STAC service for API access
3+
${DGGS_API_NAME}:
4+
url: http://dggs:8000
5+
title: Discrete Global Grid System (DGGS) Service
6+
public: true
7+
c4i: false
8+
type: api
9+
sync_type: api
10+
11+
${DGGS_TILES_NAME}:
12+
url: http://dggs:8000
13+
title: Tiles support over Discrete Global Grid System (DGGS) Service
14+
public: true
15+
c4i: false
16+
type: api
17+
sync_type: api
18+
19+
20+
permissions:
21+
- service: ${DGGS_API_NAME}
22+
resource: /openapi.json
23+
permission: read
24+
group: anonymous
25+
action: create
26+
- service: ${DGGS_API_NAME}
27+
resource: ${DGGS_DOCS_PATH_INTERNAL}
28+
permission: read
29+
group: anonymous
30+
action: create
31+
- service: ${DGGS_API_NAME}
32+
resource: /docs
33+
permission: read
34+
group: anonymous
35+
action: create
36+
- service: ${DGGS_API_NAME}
37+
resource: /api
38+
permission: read
39+
group: anonymous
40+
action: create
41+
42+
# === DGGS API ===
43+
# /${DGGS_API_NAME}/dggs/...
44+
# /${DGGS_API_NAME}/collections/{collectionId}/dggs/...
45+
46+
# Administrator permissions over whole service
47+
- service: ${DGGS_API_NAME}
48+
permission: read
49+
group: administrators
50+
action: create
51+
- service: ${DGGS_API_NAME}
52+
permission: write
53+
group: administrators
54+
action: create
55+
# Open access to the entrypoint
56+
- service: ${DGGS_API_NAME}
57+
permission: read-match
58+
group: anonymous
59+
action: create
60+
# Open access to the generic DGGRS definitions
61+
# DGGS-nested endpoints and Collections access managed by user/groups.
62+
- service: ${DGGS_API_NAME}
63+
resource: /dggs
64+
permission: read-match
65+
group: anonymous
66+
action: create
67+
# Open access to the documentation endpoints
68+
- service: ${DGGS_API_NAME}
69+
resource: /conformance
70+
permission: read-match
71+
group: anonymous
72+
action: create
73+
74+
# === Tiles API ===
75+
# /${DGGS_TILES_NAME}/{collectionId}.json
76+
# /${DGGS_TILES_NAME}/{collectionId}/{z}/{x}/{x}
77+
78+
# Administrator permissions over whole service
79+
- service: ${DGGS_TILES_NAME}
80+
permission: read
81+
group: administrators
82+
action: create
83+
- service: ${DGGS_TILES_NAME}
84+
permission: write
85+
group: administrators
86+
action: create
87+
# Tiles-only endpoint. Collections access managed by user/groups.
88+
- service: ${DGGS_TILES_NAME}
89+
permission: read-match
90+
group: anonymous
91+
action: create

‎birdhouse/components/dggs/config/magpie/docker-compose-extra.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
services:
3+
magpie:
4+
volumes:
5+
- ./components/dggs/config/magpie/config.yml:${MAGPIE_PROVIDERS_CONFIG_PATH}/dggs.yml:ro
6+
- ./components/dggs/config/magpie/config.yml:${MAGPIE_PERMISSIONS_CONFIG_PATH}/dggs.yml:ro

0 commit comments

Comments
 (0)