Skip to content

Configuration

STAC Extensions

Stacture relies on STAC extensions to function properly. If the required metadata is not available in the source STAC API it is possible to specify additional extras to add to each STAC item as an additional configuration file, but it is encouraged to have this information in the STAC metadata.

The most prominent STAC extensions are the vrt and render extensions. In addition the eo and the proj are highly encouraged.

There are plans to:

  • create a new extension for any relevant ogcapi configuration
  • use the tiles extension for support of tiles
  • use the cube extension for multidimensional data

Configuration file

Stacture uses a configuration file. This file contains settings used by the application eg. to which STAC API to connect to, which collection to use and how to render the data. The location of the configuration file is determined by the STACTURE_CONFIG_PATH environment variable. This variable should be set to the path of the configuration file on your system.

Here is an example configuration file:

terravis_url: "http://terravis"
apis:
  maps: true
collections:
  sentinel-2-l2a:
    source:
      type: stac-api
      href: https://stac.gtif.eox.at
      collection: sentinel-2-l2a
      extra:
        properties:
          renders:
            trc:
              assets:
                - trc
              rescale:
                - - 100
                  - 1500
                - - 25
                  - 1500
                - - 75
                  - 1500
            ndvi:
              assets:
                - ndvi
              rescale:
                - - -1
                  - 1
        assets:
          trc:
            title: True color image
            type: "image/tiff; application=geotiff; profile=cloud-optimized"
            roles:
              - visual
              - data
              - virtual
            href: "#/assets/trc"
            vrt:hrefs:
              - key: B04
                href: "#/assets/data/bands/1"
              - key: B03
                href: "#/assets/data/bands/2"
              - key: B02
                href: "#/assets/data/bands/3"
          ndvi:
            roles:
              - virtual
              - data
              - index
            href: "#/assets/ndvi"
            vrt:hrefs:
              - key: B04
                href: "#/assets/data/bands/1"
              - key: B05
                href: "#/assets/data/bands/4"
            title: "Normalized Difference Vegetation Index"
            vrt:algorithm: "band_arithmetic"
            vrt:algorithm_opts:
              expression: (B05-B04)/(B05+B04)
              rescale:
                - - -1
                  - 1
    map:
      default_style: default
      styles:
        default:
          render: trc
        ndvi:
          render: ndvi

terravis_url - the URL of the Terravis server.

apis - controls which apis to expose. These are set with setting maps or coverages to True or False

collections - a mapping of collection name to configuration for the collection.

The fields of the collection are:

source - the source of the collection. Next to href, the collection and type which is typically set to stac-api, there is an extras field which allows passing of additional STAC metadata to each item received from the source.

map - the map configuration which contains styles to use and the default_style

Secrets

Terravis often requires access to sensitive information, such as API keys or credentials. These are considered secrets and should be handled securely.

Two approaches are available:

  1. Environment Variables: Inject secrets as environment variables directly into the Terravis container. This is suitable for single values like API keys.

  2. Volumes/Files: Mount a volume containing secret files into the container. This is useful for managing multiple secrets or larger data sets.

Below is an example of a kubernetes secret:

terravis-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: terravis-secret
  namespace: stacture
type: Opaque
data:
  id: b64encoded_id
  secret: b64encoded_secret

To use the secret in the Terravis deployment, reference it:

Container environment variables

terravis-deployment.yaml

...
containers:
    name: terravis
    image: registry.gitlab.eox.at/vs/stacture/terravis:latest
    env:
    - name: AWS_ACCESS_KEY_ID
        valueFrom:
        secretKeyRef:
            name: terravis-secret
            key: id
    - name: AWS_SECRET_ACCESS_KEY
        valueFrom:
        secretKeyRef:
            key: secret
            name: terravis-secret
...

This example injects the id and secret values from the terravis-secret into the container's environment as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY respectively.

Additional Notes:

Remember to base64 encode your secret values before storing them in the Kubernetes secret. Choose the approach that best suits your needs and security requirements. Consult the Kubernetes documentation for more details on managing secrets.

Helm values

values.yaml

terravis:
    existingS3Secret: terravis-secret

Configmap

To apply a configuration on stacture using helm use the stacture.config field

values.yaml

stacture:
  config:
    apis:
      ...

Note that the stacture.config.terravis_url shouldn't be set in the config as the name changes based on the helm instance name. It is rather autogenerated by the values and picked up from an environment variable.