make queryables and summaries automatically updatable

.dockerignore

@@ -1,2 +1,5 @@
-env.local
-env.docker
+*
+!stac_app.py
+!requirements.txt
+!discover_queryables.sql
+!discover_summaries.sql

.gitignore

@@ -20,3 +20,6 @@ env.docker
 
 # Python
 __pycache__/
+
+# virtual environments
+venv/

Dockerfile

@@ -1,39 +1,10 @@
+FROM python:3.12-slim
 
-FROM python:3.8-slim as base
-
-FROM base as builder
-# Any python libraries that require system libraries to be installed will likely
-# need the following packages in order to build
-RUN apt-get update && apt-get install -y build-essential git
-
-ENV CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
-ENV PATH=$PATH:/install/bin
-
-ARG install_dev_dependencies=true
-
-# TODO : temporary fix
-RUN git clone https://github.com/stac-utils/stac-fastapi.git
-
-WORKDIR /stac-fastapi
-
-# TODO : checkout to working November 25 2022 version of stac-fastapi, where pgstac was bundled in stac-fastapi (now `pip install pypgstac`)
-RUN git checkout d53e792
-
-RUN pip install \
-      -e stac_fastapi/api \
-      -e stac_fastapi/types \
-      -e stac_fastapi/extensions
-RUN pip install -e stac_fastapi/pgstac
-
-RUN apt-get update \
- && DEBIAN_FRONTEND=noninteractive \
-    apt-get install --no-install-recommends --assume-yes \
-      postgresql-client
-
+# see .dockerignore file for which files are included
 COPY . /app
 
 WORKDIR /app
 
-RUN pip install -r requirements.txt
+RUN python -m pip install -r requirements.txt
 
-CMD ["uvicorn", "stac_app:app", "--reload", "--host", "0.0.0.0", "--port", "8000", "--root-path", ""]
+CMD ["uvicorn", "stac_app:app", "--host", "0.0.0.0", "--port", "8000", "--root-path", ""]

README.md

@@ -1,5 +1,73 @@
-# STAC API implementation for PAVICS (https://github.com/bird-house/birdhouse-deploy/tree/master/birdhouse)
+# STAC API implementation for [Birdhouse](https://github.com/bird-house/birdhouse-deploy/tree/master/birdhouse)
 
+This implementation extends [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac) by providing the following additional features:
+
+- [Custom Queryables](#custom-queryables)
+- [Custom Collection Summaries](#custom-collection-summaries)
+- [Settable Router Prefix](#settable-router-prefix)
+- [Settable OpenAPI paths](#settable-openapi-paths)
+
+#### Custom Queryables
+
+The [`/queryables` endpoints](https://github.com/stac-api-extensions/filter?tab=readme-ov-file#queryables) enabled by [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac) only provide basic information about the STAC items. This includes the property type (string, array, number, etc.) but not much else.
+
+This implementation adds additional postgres functions to help discover more detailed queryables information including minumums and maximums for range properties and enum values for discrete properties.
+
+> [!Note] 
+> Dates are formatted as RFC 3339 strings and JSON schemas only support minumum/maximum for numeric types so minimum and maximum dates are provided as epoch seconds (in the "minimum" and "maximum" fields) and as RFC 3339 strings in the "description" field.
+
+This also adds the following helper route `PATCH /queryables` which will update the 
+queryables stored in the database with up to date information from all items stored
+in the database.
+
+We recommend that you update the queryables after you add/remove/update any items in the database.
+
+Custom queryables are enabled by default. To disable this feature and only use the 
+queryables provided by [stac-fastapi-pgstac](https://github.com/stac-utils/stac-fastapi-pgstac), set the `STAC_DEFAULT_QUERYABLES` environment variable.
+
+#### Custom Collection Summaries
+
+Collections in STAC are strongly recommended to provide [summaries](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#summaries) and [extents](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#extents) of the items they contain. This includes the temporal and spatial extents of the whole collection as well as the minumums and maximums for range properties and enum values for discrete properties of items.
+
+These values are not updated automatically so this implementation adds additional postgres functions to help keep these collection summaries and extents up to date.
+
+This also adds the following helper route `PATCH /summaries` which will update the 
+collection summaries and extents stored in the database with up to date information from all items stored
+in the database.
+
+> [!Note]
+> These functions will only update the first extent value which defines the extent of the whole collection, additional extents that describe subsets of the collection will not be modified.
+
+Custom summaries are enabled by default. To disable this feature and only use the set the `STAC_DEFAULT_SUMMARIES` environment variable.
+
+#### Settable Router Prefix
+
+To set a custom router prefix, set the `ROUTER_PREFIX` environment variable. 
+
+For example, the following access the same route:
+
+With no router prefix set:
+
+```
+GET /collections
+```
+
+With a custom router prefix set to `/my-prefix`:
+
+```
+GET /my-prefix/collections
+```
+
+#### Settable OpenAPI paths
+
+To set a custom path for the OpenAPI routes set the following environment variables:
+
+- `OPENAPI_URL`
+    - default: `/api`
+    - returns a description of this API in JSON format
+- `DOCS_URL`
+    - default: `/api.html`
+    - returns a description of this API in HTML format
 
 
 ## CONTRIBUTING